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Preface 



The RT-U Programmer's Reference Manual describes the programmed 
requests and subroutines that are available in the system macro library 
(SYSMAC.SML) and system subroutine library (SYSLIB.OBJ). It 
provides programming examples that show how to use programmed requests and 
subroutines. 

^1 -J 1 T™J — ^J ^4-C^« 4-^ \ Af-f^-n ftnA 'DT' 11 'C>f/^rr-*'oT>-» Yviinrr rl QO/^ri V*£iO fV»a 

implementation and use of the programmed requests and the FORTRAN- 
callable subroutines. 

Chapter 2, Programmed Request Description and Examples, describes the 
individual programmed requests in detail. Program examples are included for 
each request. In addition, macros and subroutines that are used in imple- 
menting device handlers and interrupt service routines are described. 

Chapter 3, System Subroutine Description and Examples, describes in detail 
all the RT-11 FORTRAN-callable subroutines. This chapter also contains 
examples of the use of the calls to the system subroutine library. 

Appendix A, Display File Handler, describes the graphics support for the 
RT-11 operating system. Program examples are included to help you develop 
your own display program. 

Appendix B, System Macro Library, is a listing of the RT-11 System Macro 
Library (SYSMAC.SML). 

This manual is written for an advanced-level user. If you have no RT-U 
experience, or very little, read: 

Introduction to RT-11 
RT-11 System User's Guide 

In addition, FORTRAN programmers should read: 

RT-11 IRSTSIE FORTRAN IV User's Guide 
PDP-11 /FORTRAN Language Reference Manual 

If you are interested in additional programming techniques or other system 
programming topics, read the RT-11 Software Support Manual. 



Chapter 1 

Introduction to Advanced RT-11 Programming 

Programmed requests and system subroutines are available as part of the 
RT-11 Operating System and can aid you in writing reliable and efficient 
programs. 

Programmed requests provide a number of services to application programs. 
The requests function as calls to routines in the RT-11 moiiitor that perform 
these services. As system macros, they are defined in a system macro library 
that is stored on the system volume and named SYSMAC.SML. In addition, 
macro routines are available in the system macro library that can help you 
write device handlers and interrupt service routines. 

If you are a FORTRAN programmer, you can access the RT-11 monitor 
services through calls to the system subroutine library called SYSLIB.OBJ, 
which is stored on the system volume. A character string manipulation pack- 
age and two-word integer support routines are included in this library. The 
SYSLIB subroutines allow you to write almost all application programs in 
FORTRAN without having to do any assembly language coding. 

This chapter tells you how to use programmed requests and subroutines effec- 
tively in your programs. Examples are provided to demonstrate their flexibil- 
ity and value in working program.s. 

1.1 Programmed Requests 

You issue a programmed request in your source program when a certain moni- 
tor service is required. The programmed request expands into the appropriate 
machine language code during assembly time. During program execution, this 
code requests the resident monitor to supply the service represented by the 
programmed request. 

The services involve the following processes: 

1. Initialization and control of operating system characteristics 

2. Allocating system resources and reporting status 

3. Command interpretation 

4. File operations 

5. Input/output operations 

6. ForegroundA)ackground communications 

7. Timer support 

8. Program termination or suspension 

9. System job communications 

10. Extended memory functions 
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The system macro library (SYSMAC.SML) also contains several macros that 
are not programmed requests. These macros are provided to aid you in writ- 
ing: 

1. Interrupt service routines 

2. Device handlers 

They are described in Chapter 2 along with the programmed requests. 

Components of the RT-11 Operating System that support programmed re- 
quests are as follows: 

1. Single- Job Monitor 

The single-job (SJ) monitor supports most of the programmed requests. 
Table 1-4 lists the programmed requests that are supported by the SJ 
monitor. These programmed requests can manipulate files, perform input 
and output, set timer routines, check system resources and status, and 
terminate program operations. 

2. Foreground/Background Monitor 

Some programmed requests are provided for the foreground/background 
(FB) monitor only. Table 1-5 lists the programmed requests that are 
supported by the FB monitor in addition to those listed in Table 1-4. 
These programmed requests allow a program to set timer routines, sus- 
pend and resume jobs, and send messages and data between foreground 
and background jobs. 

3. Extended Memory Monitor 

The extended memory (XM) monitor provides additional programmed 
requests and features above those found in the FB monitor. The XM 
monitor extends the memory support capability of RT-11 beyond the 
28K-word (plus I/O page) restriction (imposed by the 16-bit address size) 
up to 124K words. The XM monitor's programmed requests extend a 
program's effective logical addressing space (see Table 1-5). 

4. Multi-terminal Feature 

The multi-terminal feature of RT-11 allows your program to perform 
character input/output on up to 16 terminals. Programmed requests are 
available to perform input/output, attach and detach a terminal for your 
program, set terminal and line characteristics, and return system status 
information. 

5. System Job Support 

System job support allows users in a foregroundA)ackground or extended 
memory environment to extend the present standard foreground^ack- 
ground system to include up to eight jobs. Two system jobs are presently 
provided with the RT-11 system: the error logger and device queue pro- 
gram. Programmed requests allow programs to copy channels from other 
jobs, obtain job status information about jobs in the system, and send 
messages and data between any jobs in the system. The RT-11 Software 
Support Manual describes the system job feature in more detail. 

Programmed requests perform most system resource control and interrogation 
functions. However, some communication is accomplished by directly access- 
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ing two memory areas: the system communication area and the monitor fixed- 
offset area. 

The system communication area resides in locations 40 to 57(octal) and con- 
tains parameters that describe and control execution of the current job. This 
area holds information such as the Job Status Word, starting address of the 
job, User Service Routine (USR) swapping address, and the address of the 
start of the resident monitor. Some of this information is supplied by your 
program to the monitor, while other data is supplied by the monitor and may 
not be changed. 

The second memory communication area, the fixed-offset area, is accesseu uy 
a fixed address offset from the start of the resident monitor. This area con- 
tains system constants used to control monitor operation. Your program can 
interrogate these constants to determine the condition of the operating envi- 
ronment while a job is running, but it may not change any of these values. 
The RT-11 Software Support Manual describes in detail both the system 
communication area and the fixed-offset area. 

This manual specifically describes programmed requests for RT-11 Version 4. 
Programmed requests for earlier versions of RT-11 and guidelines for their 
conversion are treated in Sections 1.1.4 and 1.1.5. 

1.1.1 Programmed Request Implementation 

1 .1 .1 .1 EMT Instructions — A programmed request is a macro call followed by 
the necessary number of arguments. The macro code that corresponds to the 
macro call of a programmed request is expanded by the MACRO assembler 
when the programmed request appears in your program. The expansion nor- 
mally arranges the arguments of the programmed request for the monitor and 
generates an EMT (emulator trap) instruction. 

When an EMT instruction is executed, control passes to the monitor. The 
low-order byte of the EMT code provides the monitor with the information 

UliClt tcilo It vVlldu J.ij.v_;ilJ.H^X oCavavC ao kj\^±xx^ j.U\^i^v^S^%^v*.> 

The execution of the EMT generates a trap through vector location 30 in low 
memory. This vector location is loaded at boot time with an address pointing 
to a location in the monitor. The monitor location contains the EMT process- 
ing code that services the interrupt caused by the EMT instruction. 

Table 1-1 shows the codes that may appear in the low-order byte of an EMT 
instruction and the interpretation of these codes by the monitor. 

Table 1-1: EMT Codes 



Low-Order Byte 


Interpretation 


377 
376 


r5 -,..vj. JJT^ 1 1 :„«„-^„ 4^U."^ T^AyfT' n*^A ^I^+%^^'y^c■ ^oT-tfr/^l fr* fKci near 

IVCadlVCU, iVi-±J. igilUlCO LillO i^.*-i -L Willi 11-1 1^1 no 1,1^11 11 i>i iiy 111^ vii.1.1 

program immediately. 

Used internally by the RT-11 monitor; your programs should 
never use this EMT since their use would lead to unpredictable 
results. 



(continued on next page) 



Introduction to Advanced RT-11 Programming 1-3 



Table 1 - 1 : EMT Codes ( Con t. ) 



Low-Order Byte 


Interpretation 


375 
374 

360-373 

340-357 
0-337 


Programmed request with several arguments; RO points to a block 
of arguments that supports the user request. 

Programmed request with one argument; RO contains a function 
code in the high-order byte and a channel code in the low-order 

byte. 

Used internally by the RT-11 monitor; your programs should 
never use these EMT codes since their use would lead to unpre- 
dictable results. 

Programmed requests with the arguments on the stack and/or in 
RO. 

Version 1 programmed requests with arguments both on the stack 
and in RO. They are supported for binary compatibility with Ver- 
sion 1 programs. 



EMT instructions should never appear in your programs except through pro- 
grammed requests. 

1.1.1.2 System Control Path Flow — Figure 1-1 shows system flow when a 
programmed request is executed. 

In Figure 1-1, a programmed request in an application (or system utility) 
program is implemented with an EMT instruction. When your program is 
executed, the EMT instruction transfers control to the EMT processor code in 
the monitor. The user PC and PS are pushed onto the stack, and the contents 
of location 30 are placed in the program counter. Location 30 points to the 
EMT processor code in the monitor. This location is loaded during bootstrap. 
Location 32 contains the Processor Status Word for the EMT trap. Byte 52 of 
the system communications area is loaded with an error code by the monitor if 
the monitor detects any errors during the EMT processing. In addition, the 
EMT processor uses RO to pass back information to the program. All other 
registers are preserved. 

The monitor either processes a programmed request entirely when it is issued 
or it performs partial processing and queues the request for further processing. 
The requests that require queued processing support completion routines (see 
Section 1.1.3.5). If a request results in an error prior to being queued, the 
completion routine is not entered, and the monitor returns to the user pro- 
gram with the carry bit set. If the request is queued, the completion routine is 
entered upon completion of further processing, regardless of the outcome. 
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Figure 1-1: System Flow During Programmed Request Execution 
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1.1.2 System Conventions 

This section describes the system conventions that must be followed for the 
correct operation of programmed requests. 

1.1.2.1 Programmed Request Format — To issue programmed requests from 
assembly language programs, you must set up the arguments in correct order 
and issue the appropriate EMT instruction. Macros have been created to help 
you do this. They are contained in the system macro library named 
SYSMAC.SML. Their use is recommended for maintaining program compati- 
bility with future releases of RT-11 and for program readability. The macro 
names for all programmed requests start with a period (.) to distinguish them 
from symbols and macros you define. 

Arguments supplied to a programmed request must be valid assembler ex- 
pressions since the arguments are used as source fields in the instructions 
(such as a MOV instruction) when the macros are expanded at assembly time. 
All programmed requests that appear in your program must appear in a 
.MCALL directive to make the macro definition available from the system 
macro library, SYSMAC.SML. If the programmed request is specified by a 
.MCALL directive, the programmed request is obtained from the system 
macro library at assembly time. 

Programmed requests have two formats that are accepted by the monitor. The 
first format specifies the programmed request followed by the arguments re- 
quired by the request. The second format specifies the programmed request, 
the address of the argument block, and the arguments that will be contained 
in the argument block. Because the way you can set up the argument block 
and specify arguments to a programmed request can vary, read the sections on 
programmed request format and on blank arguments to be sure of correct 
programmed request operation. 

FORMAT 1 

The first format for programmed requests is as follows: 

.PRGREQ Argl,Arg2,...,Argn 
where: 

.PRGREQ is the name of the programmed request 

Argl,Arg2,...,Argn are the arguments used with the request 

Programmed requests using this format generate either an EMT 374 or EMT 
340 through 357 instructions. 

Programmed requests that use an EMT 374 instruction set up RO with the 
channel number in the even (low-order) byte and the function code in the odd 
(high-order) byte, as shown in Figure 1-2. 

Figure 1-2: EMT 374 Argument 

15 87 



RO^ 



Function Code 



Channel Number 
(if applicable) 
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One programmed request that generates an EMT 374 is .DATE. The macro 
for this programmed request appears in the system macro Hbrary as: 



•MACRO .DATE 

MOM ttlO . ♦■■0400 I to 

EMT '0374 
.ENDM 



The function code, which in this case is 10 (decimal) is placed in the 
high-order byte of RO. A channel code of is placed in the low-order byte. 

For EMT 340 through 357, if there are arguments, they are placed either on 
the stack, in RO, or in RO and on the stack. 

The programmed request .CSIGEN is an example of a programmed request 
that generates an EMT 344. A simplified macro expansion of this pro- 
grammed request is: 



LINBUF .-(G. ) 
(G. ) 



.MACRO .CSIGEN DEMSPC jDEFEXT tCBTRNG ,L I NBUF 
.IIP NB <LINBUF> MOU 

MOg DE'.'SPC .-(G. ) 
.IIF NB -(LINBUF)- INC 

MOU DEFEKT ,-(6. ) 
.IF B CSTRNG 

CLR - ( B . ) 
.IFF 
.IF IDN CSTRNG »«0 

CLR - (G. ) 
, IFF 

MDV CSTRNG. -(G.) 
.ENDC 
,ENDC 

EMT -0344 
.ENDM 



When this programmed request is executed, all the specified arguments are 
placed on the user stack. Thus, the user stack would appear as shown in 
Figure 1-3. 

Figure 1-3: Stack Set by .CSIGEN Programmed Request 

High Addresses 



Stack Pointer => 
Low Addresses 



LINBUF 



DEVSPC 



DEFEXT 



CSTRING 



The EMT processor then uses these arguments in performing the function of 
the programmed request .CSIGEN. 
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FORMAT 2 

The second format for programmed requests is as follows: 



.PRGREQ Area,Argl,Arg2,...,Argn 



where; 



.PRGREQ 

Area 
Argl,Arg2,...,Argn 



is the name of the programmed request 

is the address of an argument block 

are the arguments that will be contained in the 

argument block 



This format generates an EMT 375 instruction. Programmed requests that 
call the monitor via an EMT 375 use RO as a pointer to an argument block. In 
general, the argument block appears as shown in Figure 1-4. 

Figure 1-4: EMT 375 Argument Block 



RO=>AREA: 


Function code 


Channel 




Argument 1 




Argument 2 




• 
• 
• 




Argument n 



The programmed request format uses Area as a pointer to the argument block 
that contains the arguments Argl through Argn. 

.PRGREQ Area,Argl,...,Argn 

Blank fields are permitted. However, if the Area argument is empty, the 
macro assumes that RO points to a valid argument block. If any of the fields 
Argl to Argn are empty, the corresponding entries in the argument list are left 
untouched. Thus, 

.PRGREQ Area,Argl,Arg2 

points RO to the argument block at Area and fills in the first and second 
arguments, while 

.PRGREQ Area 

points RO to the block and fills in the first word that is, the function code 
and channel number — without filling in any other arguments. Arguments 
that are left blank are discussed in the following section. 
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1.1.2.2 Blank Arguments — Any programmed request that uses ah argument 
block assumes that any argument left blank has been previously loaded by 
your program into the appropriate memory location (exceptions to this are the 
.CHCOPY and .GTJB requests). For example, when the programmed request 

.PRGREQ Area, Argl, Arg2 

is assembled, RO will point to the first word of the argument block. The first 
word has the function code in the high-order byte and the channel number in 
the low-order byte. Argl is in the second word of the argument block (that is, 
in address RO plus 2), while Arg2 is in RO plus 4. 

There are two ways to account for arguments. You can let the MACRO assem- 
bler generate the instructions needed to fill up the argument block at run 
time, or you can write these instructions in your program, leaving the argu- 
ments in the programmed request blank for those that you have written in. 

The following examples are all equivalent in that the arguments have been 
accounted for either in the program instructions or in the programmed 
request. 

MOM (*ARG1 .AREA + 2 
MOV *ARG2»AREA+4 

.PRGREQ «AREA 

is equivalent to 

MOV #AREA .RO 

• PRGREO ,#ARG1 »«ARG2 

and also to 

MOM «AREA .RO 

MOM «ARG1 .2(R0) 

MOM «ARG2.a(R0) 

MOM «CODE ! CHANNEL .(RO) 

.PRGREQ 

This last example sets up all the arguments for the programmed request prior 
to executing the programmed request. 

The following example shows how arguments are specified to the .TWAIT 
programmed request. 





.TITLE 


EXWAIT.MAC 








.MCALL 


.PRINT ..TWAIT 






START: 










WAIT; 


.TUATT 
.PRINT 
BR 


«FMTLST 

*MSG 

WAIT 






EMTLST: 


.BYTE 
.WORD 


.24 
TIME 






TIME: 


.WORD 


.10.*B0 






MSG: 


.ASCIZ 
.END 


/PRINT THIS EMERY 
START 


TEN 


SECONDS/ 



Introduction to Advanced RT-U Programming 1-9 



The .TWAIT programmed request suspends a program and requires two argu- 
ments. The first argument is area, which points to the address of a two- word 
EMT argument block; the second argument is Time, which is a pointer to two 
words of time (high-order first, low-order second) expressed in ticks. In the 
example shown above, EMTLST is specified as an argument with the pro- 
grammed request that points to the address of the EMT argument block. The 
first word of the argument block has a zero stored in the low-order byte 
representing the channel number and a function code of 24 stored in the high- 
order byte. The second word contains a symbolic pointer to the location (the 
second argument), which specifies the amount of time that the program will 
be suspended. It is defined as two words, and in this example, represents a 10- 
second interval. When run, the example program prints its message every ten 
seconds. Note that the .TWAIT programmed request requires the FB monitor 
for proper operation. 

1.1.2.3 Addressing Modes — You must make certain that the arguments 
specified are valid source fields and that the address accurately represents the 
value desired. If the value is a constant or symbolic constant, use the immedi- 
ate addressing mode [#]. If the value is in a register, use the register symbol 
[Rnj. If the value is in memory, use the label of the location whose value is the 
argument. 

For example, when a direct numerical argument is required, the immediate 
mode causes the correct value to be put into the argument block. Thus 

.PRGREQ #AreaJ4 

is correct, while 

.PRGREQ #Area,4 

is not correct since the contents of location 4 are placed into the argument 
block instead of the desired value 4. 

However, the form 

.PRGREO LIST ^NUMBER 



LIST: .WORD AREA 
NUMBER: .WORD H 

is correct since the contents of LIST are the argument block pointer and the 
contents of NUMBER are the data value. 

NOTE 

All registers e^fcept RO are preserved across a programmed 
request. In certain cases, RO contains information passed back 
by the monitor; however, unless the description of a request 
indicates that a specific value is returned in RO, the contents of 
RO are unpredictable upon return from the request. Also, with 
the exception of calls to the Command String Interpreter, the 
position of the stack pointer is preserved across a programmed 
request. 
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You must be sure that the selected mode generates the correct value as a 
source operand in a MOV instruction. Check the programmed request macro 
in the Macro Library (SYSMAC.SML) and expand the programmed request 
by hand or with the macro assembler (by using the .LIST MEB directive) to 
be sure of correct results. 

1 .1 .2.4 Keyword Macro Arguments — The RT-11 MACRO assembler supports 
keyword macro arguments. All the arguments used in programmed request 
calls can be encoded in their keyword form (see the PDP-11 MACRO-11 
Language Reference Manual for details). 

The argument code for all EMT 375 programmed requests is used for explicit 
control in expanding an EMT programmed request. In EMT 375 programmed 
requests, the high byte of the first word of the area (pointed to by RO) contams 
an identifying code for the request. Normally, this byte is set if the macro 
invocation of the programmed request specifies the area argument, and it 
remains unaffected if the programmed request omits the area argument. If the 
macro invocation contains CODE=SET, the high byte of the first word of the 
area is always set to the appropriate code, whether or not area is specified. 

If CODE=NOSET is in the macro invocation, the high byte of the first word 
of area remains unaffected. This is true whether or not area is specified. This 
allows you to avoid setting the code when the programmed request is being set 
up. This might be done because it is known to be set correctly from an earlier 
invocation of the request using the same area, or because the code was stati- 
cally set during the assembly process. 

1.1.2.5 Channels and Channel Numbers — A channel is a data structure that 
is a logical connection between your program, and a file on a mass storage 
device. The system provides 16 channels by default. When a file is opened on 
a particular device, a channel number is assigned to that file. The channel 
number can have an octal value from to 377 (0 to 255 decimal). Thus, your 
K,vorrram firct nnPris a channel through a oroerammed request by specifying 
the device and/or file name, file type, and a channel number to the monitor. 
Your program refers to that file or device in all I/O operations thereafter by 
the assigned channel number. You can specify a device (non-file-structured) 
or a device and file name (file-structured). 

1.1.2.6 Device Blocks — A device block is a four-word block of Radix-50 
information. You set up the block to specify a physical or logical device naine, 
file name, and file type for use with a programmed request. This information 
is passed to the monitor when your program opens a file to locate the refer- 
enced device and the file name in the corresponding directory. 

For example, a device block representing the file FILE.TYP on device DK: 
could be written as 

,RAD50 /DK / 
.RAD50 /FIL/ 
,RAD50 /E / 
.RfiD50 /TYP/ 



Introduction to Advanced RT-11 Programming 1-11 



The first word contains the device name, the second and third words contain 
the file name, and the fourth word contains the file type. Device, file name, 
and file type must each be left-justified in the appropriate field. This string 
could also have been written as 

,RAD50 /DK FILE TYP/ 

Spaces must fill out each field. Also, the colon and period separators must not 
appear in the string since they are only used by the Command String Inter- 
preter to delimit the various fields. 

1.1.2.7 Programmed Request Errors — Programmed requests use three meth- 
ods of reporting errors detected by the monitor: 

1. Setting the carry bit of the processor status word (PS) 

2. Reporting the error code in byte 52 of the system communications area 

3. Generating a monitor error message 

If a programmed request has been executed unsuccessfully, the monitor re- 
turns to your program with the carry bit set. The carry bit is returned clear 
after the normal termination of a programmed request. Almost all requests 
should be followed by a Branch Carry Set (BCS) or Branch Carry Clear 
(BCC) instruction to detect a possible error. 

Because some programmed requests have several error codes — that is, errors 
can be generated for different reasons — byte 52 in the system communica- 
tions area is used to receive the error code. Thus, when the carry bit is set, 
check byte 52 to find out the kind of error that occurred in the program. The 
meanings of values in the error byte are described individually for each re- 
quest. The error byte is always zero when the carry bit is clear. Your program 
should reference byte 52 with absolute addressing. Always address location 52 
as a byte, never as a word, since byte 53 has a different usage. The following 
example shows how byte 52 can be tested for the error code. 

ERRBYT=52 

.PRGREQ AREA,ARG1 >. . . ,ARG2 

W l^ ^ L_l\ it '_J l\ 



ERROR: TSTB @«ERRBYT 

Error messages generated by the monitor are caused by fatal errors, which 
cause your program to terminate im-m.ediately. Some fatal errors can be inter- 
cepted and have their values returned in byte 52 (see the .HERR/.SERR 
programmed requests). 

1.1.2.8 User Service Routine (USR) Requirement ~ Many 
programmed requests require the USR to be in memory. Some of these re- 
quests always require a fresh copy of the USR to be read in because the code 
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to execute them resides in the USR buffer area. Since the buffer area gets 
overlaid by data used to perform other system functions, the USR must be 
read in from the system device even if there is a copy of the USR presently in 
memory. Table 1-2 shows the programmed requests that require the USR. 

Table 1-2: Programmed Requests Requiring the USR 



Request 


Monitor 










SJ 


FB 


XM 


.CDFN 


yes* 


no 


no 


.CLOSE (see Note 1) 


yes 


yes 


yes 


.CSIGEN 


yes 


yes 


yes 


.CSISPC 


yes 


yes 


yes 


.DELETE 


yes 


yes 


yes 


.DSTATUS 


yes 


yes 


yes 


.ENTER 


yes 


yes 


yes 


.EXIT 


yes 


yes 


yes 


.FETCH 


yes 


yes 


yes 


.GTLIN 


yes 


yes 


yes 


.HRESET 


yes 


no 


no 


.LOCK (see Note 2) 


yes 


yes 


yes 


.LOOKUP 


yes 


yes 


yes 


.QSET 


yes* 


yes* 


yes 


.RELEAS 


yes 


yes 


yes 


.RENAME 


yes 


yes 


yes 


.SRESET 


yes* 


no 


no 


.TLOCK (see Note 3) 


yes 


yes 


yes 



Note 1: Only if channel was opened with an .ENTER pro- 
grammed request 

Note 2: Only if the USR is in a swapping state 

Note 3: Only if the USR is not in use by another job 

* The requests marked with an asterisk always require a 
fresh copy of the USR to be read in before they can be 
executed. 

USR requirements for programmed requests differ between the SJ and FB 
monitors as shown in the table. The .CLOSE programmed request on non-file- 
structured devices, such as a line printer or terminal, does not 
require the USR under any monitor. 

The USR is not reentrant and cannot be shared by concurrent jobs. Thus, 
when the USR is in use by one job, another job requiring it must queue up for 
it. This is particularly important for concurrent jobs when devices such as 
magnetic tape or cassette are active. For example, USR file operations on tape 
-^oTTiVoo roniiiro q connontial dParrh of thp fRTTip When a baclcErround nroe'ram 
is running the USR, the foreground job is locked out until the tape operation 
is completed. You should be aware that this operation may take considerable 
time. The .SPFUN request can be used to perform asynchronous directory 
operations on tape. In the FB and XM monitors, the .TLOCK request can be 
used by a job to check USR availability. 
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Any request that requires the USR to be in memory can also require that a 
portion of your program be saved temporarily in the system device swap file 
(that is, "swapped out" and stored in the file SWAP.SYS to provide room for 
the USR). The USR is then read into memory. This swapping is invisible to 
you in normal operation. However, you can optimize programs so that they 
require little or no swapping, thereby saving time. 

Consider the following items if a swap operation is necessary. 

1. The background job 

If a .SETTOP request in a background job specifies an address beyond the 
point at which the USR normally resides, a swap is required when the 
USR is called. Section 2.4.50 details the operation of the .SETTOP re- 
quest. This case is not encountered in XM because the USR is always 
resident. 

2. The value of location 46 

If you assemble an address into word 46 or move a value there while the 
program is running, RT-11 uses the contents of that word as an alternate 
place to swap the USR. If location 46 is zero, this indicates that the USR 
will be at its normal location in high memory. If the USR does not require 
swapping, this value is ignored. 

A foreground job must always have a value in location 46 unless it is 
certain that the USR will never be swapped. If the foreground job does not 
allow space for the USR and a swap is required, a fatal error occurs. The 
SET USR NOSWAP command makes the USR permanently resident. 

If you specify an alternate address in location 46, the SJ monitor does not 
verify the validity of the USR swap address. Thus, if the area to be 
swapped overlays the resident monitor, the system is destroyed. 

3. Monitor offset 374 

The contents of monitor offset 374 indicate the size of the USR in bytes. 
Programs should use this information to dynamically determine the size of 
the region needed to swap the USR. 

4. Protecting program areas 

Make sure that certain areas of your program do not get overlaid when you 
swap in the USR. These areas are the program stack, any parameter block 
for calls to the USR, the EMT instruction that invoked the USR, I/O 
buffers, device handlers, interrupt service routines, queue elements, de- 
fined channels, and completion routines in use when the USR is being 
called. 

The RT-11 Software Support Manual provides additional information on the 
USR. 

1.1.3 Using Programmed Requests 

This section describes how to use and implement programmed requests to 
access the various monitor services. Chapter 2 contains, in alphabetical order, 
detailed descriptions of each request, including examples. 
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1.1.3.1 Initialization and Control — Typically, you use several programmed 
requests to control the operating environment in which your program is run- 
ning. These requests can include control of memory allocation, I/O access, 
devices, and error processing. 

MEMORY ALLOCATION 

The memory needs of a program are specified to the monitor by the .SETTOP 
request. When loaded, a program occupies the memory specified by its image 
created at link time. To obtain more memory, a .SETTOP request is exe- 
cuted, with RO containing the highest address desired. The monitor returns 
the highest address available. Resident handlers or foreground jobs can pre- 
vent all the memory that is desired from being available to the program. If the 
memory requirements of the running program permit, the monitor retains the 
User Service Routine (USR) in memory, which reduces swapping. Otherwise, 
the monitor will automatically swap part of the user program to the swap file 
called SWAP.SYS on the system device. The .SETTOP request then allows 
you to determine how much memory is available and to control monitor 
swapping characteristics. See the .SETTOP programmed request in Chapter 
2 for special optional features provided in an extended memory environment. 
Additional information on the .SETTOP request is also given in the RT-11 
Software Support Manual. 

If a program needs so much memory that the USR must swap, swapping will 
automatically occur whenever a USR call is made. However, if a program 
knows what file operations are necessary, and these operations can be consoli- 
dated and performed in localized areas, the efficiency of the system can be 
enhanced in the following manner: request the USR to be swapped in, have it 
remain resident while a series of consecutive USR operations is performed, 
then swap the USR out when the sequence of operations is completed. 

Three programmed requests control USR swapping. The request .LOCK 
causes the USR to be made resident for a series of file operations. It can 

^„^«rt^-r% ^;+U«>. V»,T. i'1 \ i-opiniir-ivtn- a T^p^fiop r\f vrnnr TTtTocrmTn to Hp w/riftpn to tVlP 

UUCieiUC ClLllCl fjy ' V-l./ XCilU.i.Xi.XAg t* y\Ji.\jl\yli. vi Jrv./^A ^j.w^ .■.»..... ...... ^^ "-.- -.- 

swap blocks prior to reading in the USR; (2) only requiring a fresh copy of 
the USR if the USR buffer is overwritten; or (3) not requiring the USR to 
be read in if it finds the USR intact. The request 
.UNLOCK swaps your program back in if it was swapped out and the USR is 
overwritten; otherwise, no swapping occurs. The request .TLOCK makes the 
USR resident in foreground/background programs, but only if the USR is not 
currently servicing another job's file requests at the time the .TLOCK request 
is issued. This check prevents a job from becoming blocked while the USR is 
processing another job's request. When a .TLOCK succeeds, the USR is ready 
to perform an operation immediately. In a single-job environment, the 
.TLOCK request performs exactly like the .LOCK request. 

is, 16 files can be active at one time. Up to 256 (decimal) channels can be 
activated with the .CDFN request. This request sets aside memory inside the 
job area to provide the storage required for the status information on the 
additional channels. Once the .CDFN request has been executed, as many 
channels as specified can be active simultaneously. Use the .CDFN request 
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during the initialization phase of your program. The keyboard monitor com- 
mand CLOSE does not work if you define new input or output channels with 
the .CDFN programmed request. 

The .CNTXSW request allows the job to add memory locations to the list of 
items to be context-switched. The request itself does not cause a context 
switch to occur. 

INPUT/OUTPUT ACCESS 

Each pending I/O, message, or timer request must be placed into one of the 
monitor queues which is then processed on a first-in first-out basis by the 
monitor. In RT-11, all I/O transfers are queued to allow asynchronous pro- 
cessing of the request. A queue is a list of elements, each element being seven 
words long (ten words [decimal] long when using the extended memory moni- 
tor). When your program issues a data transfer programmed request, the 
information specifying the transfer is stored by the monitor in a queue ele- 
ment. This information is passed to the device handler, which then processes 
the I/O transfer. 

Each job, whether background or foreground, initially has only a single queue 
element available. Additional queue elements may be set aside with a .QSET 
request. The .QSET request declares where in memory the additional queue 
elements will go and how many elements there will be. If you do not include a 
.QSET request in your program, the monitor uses the queue element set aside 
in the job's impure area. In this case, since only one element is available for 
each job, all operations would be synchronous. That is, any request issued 
when the available queue element list is empty has to wait for that element to 
become free. The number of queue elements necessary equals the number of 
asynchronous operations pending at any time. 

DEVICES 

The .DEVICE request turns off any special devices that are being used by the 
running program upon program termination. This request (available only in 
FB or XM) allows you to specify a set of device control register addresses and 
a value to be set in each register on job exit. When a job is 
terminated — either normally, by an error condition, or by a CTRL/C — the 
specified values are set in the specified locations. 

Loading a background job with a GET, R, or RUN command, or loading a 
foreground or system job with a FRUN and SRUN command, respectively, 
alters most locations in the vector area to 476. RT-11 automatically pre- 
vents alteration of all locations used by the system, such as the clock, the 
console terminal, and all vectors used by handlers that are loaded. If a fore- 
ground job in a foreground/background environment accesses a device directly 
through an in-line interrupt service routine, the foreground job must notify 
the monitor that it must have exclusive use of the vectors. You use the 
.PROTECT programmed request to allow the foreground job to gain exclusive 
use of a vector or set of vectors. The .PROTECT request can also be used by 
either the foreground or background job, prior to setting the contents of a 
vector, to test whether the vectors are already controlled by a job. This 
serves as further protection against jobs interfering with each other. An 
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.UNPROTECT programmed request relinquishes control of a vector, making 
the vector available to both the background and foreground jobs. 

The request .SPFUN is available for performing special functions on devices 
such as magnetic tape. .SPFUN requests are used for such functions as rewind 
or space-forward operations. 

ERROR PROCESSING 

During the course of program execution, errors can occur that cause the moni- 
tor to stop and print a MON-F error message. Examples include directory I/O 
ar-r-^r.^ mr»nifr.r T/H prrnre nn fVip svstpm device, or I/O reouests to nonexistent 
devices. Some programs cannot afford to allow the monitor to abort the job 
because of such errors. For example, in the case of RT-11 multi-user BASIC, a 
directory I/O error affecting only one of the users should not cause the whole 
program to abort. For such applications, a pair of requests is provided, .HERR 
and .SERR. A .HERR request (normal default) indicates that the monitor 
will handle severe errors and stop the job. A .SERR request causes the moni- 
tor to return most errors to your program in byte 52 for appropriate action. 

In addition to processing I/O errors through .HERR and .SERR requests, you 
can also handle certain fatal errors through the .TRPSET or .SFPA requests. 
You use these requests to prevent your program from aborting due to a trap to 
location 4 or 10 (octal), or to the exception traps of the Floating Point Proces- 
sor (FPP) or Floating Point Instruction Set (FIS). A .TRPSET request speci- 
fies the address of a routine that the monitor enters when a trap to location 4 
or 10 occurs. A .SFPA request specifies the address of a floating-point excep- 
tion routine that is called when an exception trap occurs. 

1.1.3.2 Allocating System Resources and Reporting Status — Several pro- 
grammed requests interrogate the system for specific details about a device or 
file that your program may be using. 

The .DATE request obtains the system date, which then can be printed on a 

report or entertJU as a uata icuuiu 111 a inc. iiiC 1^1111^ v-t v*i*j x>^i« «^ v,« 

with a .GTIM request and used in the same way. A program can set the 
system date and/or time by using the .SDTTM programmed request. Chang- 
ing the date or time has no effect on any outstanding mark time or timed wait 
requests. 

With a .GTJB request you can obtain information on whether the job is 
running in the foreground or background, the memory limits of the job, the 
virtual high limit for a job created with the linker /V option (XM only), the 
unit number of the job's console terminal (if you are using the multi-terminal 
feature), the address of the job's channel area, the address of the job's impure 
area, and the job's logical job name (if you are using a monitor with the 
system job feature). 

Status information on a file — such as its starting block, its length, and the 
device it is located on — can be obtained with a .CSTATUS request (avail- 
able only in FB and XM). Status information on a device — such as its block 
length and controller-assignment number — can be obtained with a 
.DSTATUS request. 
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The .MTSTAT programmed request provides multi-terminal status informa- 
tion when the multi-terminal feature is being used. 

The programmed requests .MFPS and .MTPS read the priority bits and set 
the priority and T-bits in the processor status word (PSW). These requests 
allow a program to run without change on any processor from an LSI-11 to a 
PDP-11/60. 

1.1.3.3 Command Interpretation — Two of the most useful programmed re- 
quests are .CSIGEN and .CSISPC. These requests call the Command String 
Interpreter (CSI), which is part of the USR. They are used to process standard 
RT-11 command strings in the general form 

*Dev:Output/Option=Dev:Input/Option 

The asterisk is printed on the terminal by the monitor's programmed request 
processor. The RT-11 system programs use the same command string (see the 
RT-11 System User's Guide). 

Use the .CSIGEN request to enter a command string at the terminal. The CSI 
analyzes the string for correct syntax, automatically loads the required device 
handlers into memory, opens the files specified in the command, and returns 
to your program with option information. Thus, with one request, a language 
processor such as the FORTRAN compiler is ready to input from the source 
files and output the listing and binary files. You can specify the available 
options in the command string to control the operation of the language proces- 
sor. The .CSIGEN request uses channels through 2 to accommodate three 
output file specifications and channels 3 through 10 (octal) to accommodate 
six input file specifications. 

The programmed request .CSISPC provides you with the services of the com- 
mand processor, but allows you to do your own device and file manipulation. 
When you use .CSISPC, the CSI obtains a command string, analyzes it syn- 
tactically, places it into tabular form, and passes the table to your program for 
appropriate action. 

The .GTLIN request obtains one line of input at a time instead of one charac- 
ter. This request supports the indirect file function and allows your program 
to obtain one line at a time from an indirect file. Thus, if your program was 
started through an indirect file, the line is taken from the indirect file and not 
the terminal. 

1.1.3.4 File Operations — A device handler is the normal RT-11 interface 
between the monitor and the peripheral device on which file operations are 
performed. The console terminal handlers (in FB and XM) and the interjob 
message handlers are part of the resident monitor and require no attention on 
your part. All other device handlers are loaded into memory with either a 
.FETCH request from the program or a LOAD command from the keyboard 
before any other request can access that device. Section 1.1.3.5 of this manual 
describes the use of programmed requests for performing I/O operations. The 
RT-11 Software Support Manual describes how to write device handlers for 
RT-11. 
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Once the handler is in memory, a .LOOKUP request can locate existing files 
and open them for access. New files are created with an .ENTER request. 
Space for the file can be defined and allocated as: 

1. One-half the size of the largest unused space or all of the second largest 
space, whichever is larger (the default) 

2. A space of a specific size 

3. As much space as possible 

The way the system allocates the space depends upon the parameter specified 
by you to the file size argument of the .ENTER request. 

When file operations are completed, a .CLOSE request makes the new file 
permanent in the directory, or a .PURGE request can free the channel with- 
out making the file permanent in the directory. Existing permanent files can 
be renamed with a .RENAME request or deleted with a .DELETE request. 

Two other requests, .SAVESTATUS and .REOPEN, add to the flexibility of 
file operations. The .SAVESTATUS request rem-em-bers the current status of 
a file that has been opened with a .LOOKUP request and makes the file 
temporarily inactive, thus freeing the channel for use by another file. The 
.REOPEN request causes the inactive file to be reactivated on any free chan- 
nel, and I/O continues on that channel. In this manner, you can open more 
files than there are channels. If, in addition, you lock the USR in memory, you 
can open all the files your job needs while maintaining system swapping 
efficiency. The procedure is: 

1. Lock the USR in memory, and open the files that are needed. 

2. Issue the .SAVESTATUS request. 

3. Release the USR. 

He. issue iX .xV-CjWX J-iJxN ici^UcoL cd^^ii n-iilc a. AAxt; j.u xx^^^^vi*^*^. 

5. Lock USR, and use the .CLOSE request to make the files permanent. 

Because a .REOPEN request does not require any I/O, all USR swapping and 
directory motion can be isolated in the initialization code for an application, 
and many files can be manipulated at one time. 

1.1.3.5 Input/Output Operations — You can perform I/O in three different 
modes: 

• synchronous 

• asynchronous 

• event-driven 

These modes allow you to optimize the overlap of CPU and I/O processing. 

The programmed requests .READW and .WRITW perform synchronous 
I/O — that is, the instruction following the request is not executed until the 
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I/O transfer is completely finished; thus the program and the I/O process are 
synchronized. 

The program requests .READ, .WRITE, and .WAIT perform asynchronous 
I/O — that is, the .READ or .WRITE request adds the transfer request to the 
queue for the device; if the device is inactive, the transfer begins; control 
returns to the user program before the transfer is completed. The .WAIT 
programmed request, however, blocks the program until the transfer is com- 
pleted. This allows the I/O operation to be completed before any further 
processing is done. Asynchronous I/O is most commonly used for double 
buffering. 

Program requests such as .READC and .WRITEC perform event-driven 
I/O — that is, they initiate a completion routine when the transfer is fin- 
ished. 

Event-driven I/O is practical for conditions where system throughput is im- 
portant, where jobs are divided into overlapping processes, or where processor 
timings are random. The last condition is the most attractive case for using 
event-driven I/O because processor timing may range up to infinity in that a 
process is never completed. 

Since the completion routine is essential to event-driven I/O, the next section 
presents general guidelines for writing completion routines. 

COMPLETION ROUTINES 

Completion routines are part of your program. They execute following the 
completion of some external operation, interrupting the normal program flow. 
On entry to an I/O completion routine. Register contains the contents of the 
Channel Status Word and Register 1 contains the channel number for the 
operation. The carry bit is not significant. 

Completion routines are handled differently, depending on whether the pro- 
gram is being run under the SJ monitor or the FB and XM monitors. Under 
the SJ monitor, completion routines are totally asynchronous and can inter- 
rupt each other. An interrupted completion routine is resumed when the 
interrupting routine is finished. Under the FB and XM monitors, completion 
routines do not internapt one another. Instead, they are queued, and the next 
routine is not entered until the first is completed. 

If the foreground job is running and a foreground I/O transfer completes and 
wants a completion routine, that routine is entered immediately if the fore- 
ground job is not already executing a completion routine. If it is in a comple- 
tion routine, that routine continues to termination, at which point other com- 
pletion routines are entered in a first-in first-out order. If the background job 
is running (even in a completion routine) and a foreground I/O transfer com- 
pletes with a specified completion routine, execution of the background job is 
suspended and the foreground routine is entered immediately. 

Also under the FB monitor, it is possible to request a completion routine from 
an in-Hne interrupt service routine through a .SYNCH programmed request. 
This allows the program to issue other programmed requests to the monitor. 
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Restrictions that must be observed when writing completion routines are as 

j-OiiOWSI 

1. Requests that require the USR should not be issued within a completion 
routine. A fatal monitor error is generated if the USR is called from a 
completion routine. 

2. Completion routines should never reside in memory space that is used for 
the USR, since the USR can be interrupted when I/O terminates and the 
completion routine is entered. If the USR has overlaid the routine, control 
passes to a random place in the USR, with a HALT or error trap being the 
likely result. 

3. Registers other than RO or Rl must be saved upon entry to completion 
routines and restored upon exiting. Other registers cannot transfer data 
between the mainline program and the completion routine. 

4. Under the XM monitor, completion routines must remain mapped while 
the request is active and the routine can be called. 

5. The completion routine must exit with an RTS PC instruction because the 
routine was called from the monitor with a JSR PC,ADDR, where ADDR 
is the user-supplied entry point address. If you exit completion routines 
with an .EXIT request, your job will abort. An exit from a completion 
routine can be done by using an .SPCPS request to change the mainline 
PC to point to an .EXIT in the main code. As soon as all completion 
routines are done, the exit will be executed. 

6. Under the XM monitor, completion routines scheduled as a result of a 
.SYNCH run in kernel mapping, not user mapping. 

Frequently, a program's completion routine needs to change the flow of con- 
trol of the mainline code. For example, you may wish to establish a schedule 
among the various tasks of an application program after a certain time has 
elapsed, or after an I/O operation is complete. Such an application needs to 
redirect the mainline code to a scheduling subroutine when the application's 
timer or read/write completion routine runs. The .SPCPS programmed re- 
quest, which can only be used in a foreground/background or extended mem- 
ory environment, saves the mainline code program counter and processor 
status word, and changes the mainline code program counter to a new value. 
If the mainline code is performing a monitor request, that request finishes 
before rerouting can occur. 

TERMINAL INPUT/OUTPUT 

Several programmed requests are available to provide an I/O capability with 
the console terminal: a .TTYIN request obtains a character from the console; 
a .TTYOUT request prints a character on the terminal; long strings of 

1 1,'11> ..•,1,1 TMTiTATm 

cnaracters — even muitipie nnes — are ouipui wiin me .rruiN i request. 
Programs can also issue .TTINR and .TTOUTR requests, which indicate that 
a character is not available or that the output buffer is full. The program can 
then resume operation and try again at a later time. A .RCTRLO request 
forces the terminal output to be reactivated after a CTRL/0 has been typed to 
suppress it, so that urgent messages will be printed. 
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You can use the .TTYIN/.TTINR requests in special (single-character) mode 
by setting bit 12 of the Job Status Word. See the .TTYIN programmed re- 
quest for a description of special mode. 

MULTI-TERMINAL REQUESTS 

The RT-11 multi-terminal feature allows your program to perform input/out- 
put on up to 16 terminals. Several programmed requests allow you to perform 
I/O on these terminals. Before issuing any of these programmed requests to a 
terminal, you must issue the .MTATCH request, which reserves the specified 
terminal for exclusive use by your program. The terminal cannot then be used 
by any other job until you issue the .MTDTCH request to detach the 
terminal. 

The .MTIN request returns to a program characters that are typed at the 
terminal, while the .MTOUT and .MTPRNT requests send characters to a 
terminal. These requests are analogous to the .TTYIN, .TTYOUT, and 
.PRINT requests. Note that the .TTYIN/.TTINR, .TTYOUT/.TTOUTR, and 
.PRINT requests can only be used with the console terminal. 

You can set terminal and line characteristics with the .MTSET request. You 
provide a four- word status block that contains the terminal status word, the 
character of the terminal requiring fillers and the number of fillers required 
for this character, the width of the carriage (80 characters by default), and 
system terminal status. The status of a terminal can be obtained by issuing 
the .MTGET request. The .MTSTAT request provides multi-terminal system 
status information. 

1.1.3.6 Foreground/Background Communications — Communication between 
foreground and background jobs is obtained through the programmed re- 
quests .SDAT and .RCVD. These requests also have three modes (synchro- 
nous, asynchronous, and event-driven) that allow transfer of buffers between 
the two jobs as if I/O were being done. The sending job treats a .SDAT request 
as a write, and the receiving job treats .RCVD as a read. In the case of .RCVD 
requests, the receiving buffer must be one word longer than the number of 
words expected. When the data transfer is completed, the first word of the 
buffer contains the number of words actually sent. 

Jobs receiving messages can be activated when messages are sent through 
.RCVDC completion routines, while the sending jobs use .SDATC completion 
routines. The .MWAIT request is used for synchronizing message requests. It 
is similar to the .WAIT request that is used for normal I/O. 

If you want one job in a foreground/background environment to read or write 
data in a file opened by the other job, use the .CHCOPY request. For exam- 
ple, when the background job is processing data that is being collected by the 
foreground job, the .CHCOPY request allows you to obtain channel informa- 
tion from the foreground job and to use that channel information to control a 
read or write request. 

The foreground/background monitor always causes a context switch of critical 
items such as machine registers, the job status area, and floating-point proc- 
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essor registers when a different job is scheduled to run because it has a higher 
priority, or because the current job is blocked and a lower priority job is 
runnable. When the monitor saves a job's context, it saves the job-dependent 
information on the job's stack so that this information can be restored when 
the job is runnable again. 

1.1.3.7 Timer Support — Timer support by the monitor is provided through 
the .MRKT request. With the .MRKT request, you specify the address of a 
routine that is to be entered after a specified number of clock ticks. Like I/O 
completion routines, .MRKT routines are asynchronous and independent of 
the main program. After the specified time elapses, the main program is 
interrupted, the timer completion routine executes, and control returns to the 
interrupted program. 

Pending .MRKT requests — as many as the queue can hold — are identified 
by number. Pending timer requests can be canceled with a .CMKT request. 
.MRKT requests are normally used as a scheduling tool where jobs are sched- 
uled on the basis of clock events, detected by timer completion routines. 

A job can be suspended for a specified time interval with a .TWAIT request. 
For example, the .TWAIT request will allow a compute-bound job to relin- 
quish CPU time to the rest of the system, permitting other jobs to run. The 
.TWAIT request does not work under the SJ monitor. 

1.1.3.8 Program Termination or Suspension — Many jobs come to an execu- 
tion point where there is no further processing necessary until an external event 
occurs. In the FB or XM environment such a job can issue a .SPND request to 
suspend the execution of that job. While the foreground job is suspended, the 
background job runs. WTien the desired external event occurs, it is detected by 
a previously requested completion routine, which executes a .RSUM request 
to continue the job at the point where it was suspended. 

When a job is ready to terminate or reaches a serious error condition, it can 
reset the system with the .SRESET and .HRESET requests. .SRESET is a 
soft reset. That is, the monitor data base is reinitialized, but queued I/O is 
allowed to run to completion. .HRESET is a hard reset where all I/O for the 
job is stopped (by a RESET instruction in the SJ monitor or by calls to the 
handlers in an FB environment). 

Use the programmed request .EXIT in a background job to return control to 
the keyboard monitor by causing program termination. If Register contains 
a zero upon execution of this request, a hard reset is performed, and the 
commands REENTER, CLOSE, and START are disabled. If Register con- 
tains a non-zero value upon exit from your program, a soft reset is done, and 
these commands are not disabled. In a foreground job, an .EXIT programmed 
request stops the job but does not return control to the keyboard monitor. The 
job can be removed from memory by the UNLOAD command. 

You may initiate the execution of another program with a .CHAIN request 
from a background job. Files remain open across a .CHAIN request and data 
is passed in memory to the chained job, so that it can adjust processing. In 
FORTRAN, channel information is stored in the impure area, and this infor- 
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mation is not preserved across a .CHAIN request. Thus, close any channels in 
the first program, and reopen them in the program being chained to. ^ 

1.1.3.9 System Job Communications — System job support allows communi- 
cations between any two jobs in the system. The background job, designated 
by the logical job name 'B', and the foreground job, designated by the logical 
job name 'F', can send and receive messages between each other by using the 
.RCVD and .SDAT programmed requests. 

All jobs (that is, background, foreground, and system jobs) can communicate 
with each other by using the Message Handler (MQ). The MQ handler per- 
forms like an ordinary RT-11 device handler in the way it accepts and 
dispatches I/O requests from the queued I/O system. This permits all .READ 
and .WRITE requests to send messages between any two jobs as if they were 
data transfers to files. Both the sending and receiving job must issue a 
.LOOKUP request on a channel and use 'MQ' as the device specification and 
the logical job name of the job with which they are communicating as the file 
specification. In the case of .READ requests, the receiving buffer must be one 
word longer than the number of words expected. When the data transfer is 
completed, the first word of the buffer contains the number of words actually 
sent (identical to the .RCVD requests). This does not apply to the .WRITE 
requests; the first word of the sending buffer is the first word of the message to 
be sent. Note that the Message Handler (MQ) can also be used under the 
distributed FB monitor; it does not require the system job special feature. 

Care should be taken when assigning logical job names to system jobs. Pro- 
grammed requests such as .LOOKUP, .CHCOPY, and .GTJB must use the 
job's current logical job name (see the RT-11 System User's Guide). 

1.1.3.10 Extended Memory Functions — The RT-11 extended memory (XM) 
monitor permits MACRO programs to access extended memory by mapping 
their virtual addresses to physical locations in memory. This is done in con- 
junction with a hardware option called the Memory Management Unit that 
converts a 16-bit virtual address to an 18-bit physical address. You access 
extended memory in a program through programmed requests. 

In accessing extended memory, you must first establish window and region 
definition blocks. Next, you must specify the amount of physical memory the 
program requires and describe the virtual addresses you plan to use. Do this 
by creating regions and windows. Then, associate virtual addresses with phys- 
ical locations by mapping the windows to the regions. You can remap a win- 
dow to another region or part of a region, or you can eliminate a window or a 
region. Once the initial data structures are set up, you can manipulate the 
mapping of windows to regions that best meet your requirements. 

There are four types of extended memory programmed requests: 

1. Window requests 3. Map requests 

2, Region reque.sts 4. Status requests 

The window and region requests have their own data structures. RT-11 pro- 
vides the macro .WDBBK to create a window definition block and the macro 
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.RDBBK to create a region definition block. Both macros automatically de- 
fine offsets and bit names. Two other macros, .WDBDF and .RDBDF, define 
only the offsets and bit names. 

The programmed request .CRAW is used to create a window. To eliminate a 
window, use the .ELAW request. A region is created using the .CRRG request. 
You return a region to the free list of memory with the .ELRG request. 

You map a window to a region with the .MAP request. If a window is already 
mapped to a region, this window is unmapped and the new one is mapped. 

of a window with the .GMCX request. 

Certain programmed requests are restricted when they are in an extended 
memory environment. These programmed requests and their restrictions are 
as follows: 

.CDFN All channels must be in the lower 28K of memory (but 

not in the Px\Rl region, 20000-37776 octal). 

.QSET All queue elements must be 10 (decimal) words long and 

in the lower 28K of memory (but not in the PARI region, 
20000-37776 octal). 

.SETTOP Effective only in the virtual address space that is mapped 
at the time the request is issued, unless the job was linked 
with the /V option (see the RT-11 System User's Guide). 

.CNTXSW Not usable in virtual jobs. 

Detailed information on programmed requests in an extended memory envi- 
ronment is given in the RT-11 Software Support Manual. 

1.1.3.11 Interrupt Service Routines — The system macro library 
(SYSMAC.SML) contains some macros that are not programmed requests, 
but are used like programmed requests in interrupt service communication to 
the monitor. The first macro call m every interrupt routine is .INTEN, which 
causes the system to use the system stack for interrupt service and allows the 
monitor scheduler to make note of the interrupt. If device service is all the 
routine does, .INTEN is the only call it need make. If you need to issue one or 
more programmed requests, such as .READ or .WRITE from the interrupt 
service routine, you must issue the .SYNCH call. The .INTEN call described 
above switched execution to the system state, and since programmed requests 
can only be made in the user state, the .SYNCH call handles the switch back 
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tion routine. When the .SYNCH is finished, the completion routine can exe- 
cute programmed requests, initiate I/O, and resume the mainline code. The 
first word after the .SYNCH call is the return address on error, while the 
second word is the return on success. The RT-11 Software Support Manual 
contains a detailed description of interrupt service routines. 
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1.1.3.12 Device Handlers — The system macro library (SYSMAC.SML) con- 
tains several macros that simplify the writing of a device handler. A device 
handler is divided into several sections. These sections are as follows: 

• Preamble section • Interrupt service section 

• Header section • I/O completion section 

• I/O initiation section • Termination section 

The .DRDEF macro is used near the beginning of your device handler, and 
performs much of the work in the preamble section. The .DRBEG macro sets 
up the first five words in the header section, stores five words of information in 
block of the handler file, and creates some global symbols. The .DRAST 
macro sets up the interrupt entry point and the abort entry point in the 
interrupt service section, and lowers the processor priority. The .DRFIN 
macro generates the instructions for the jump back to the monitor at the end 
of the handler I/O completion routine. The .DREND macro generates handler 
termination code. The .DRBOT macro sets up the primary driver. A primary 
driver must be added to a standard handler for a data device to create a 
system device handler. In addition, the .DRSET macro sets up the option 
table for the SET command in block of the device handler file. The .DRVTB 
macro sets up a table of vectors for devices that require more than one vector. 

Each of the device handler macros is described in Chapter 2. The RT-11 
Software Support Manual details the use of these macros in writing a device 
handler. 

1.1.4 Compatibility witii Previous RT-11 Versions 

Programmed requests were implemented differently in each major release of 
RT-11. The following sections outline the changes that were made to the 
programmed requests from version to version. 

1.1.4.1 Version 1 Programmed Requests — Programmed requests provided 
with the first release of RT-11, such as .READ and .WRITE, were designed 
for a single-user, single-job environment. As such, they differ significantly 
from the programmed requests of the later versions. For Version 1 requests, 
arguments were pushed on the stack instead of being stored, as they are 
presently, in an argument block. The channel number was limited to the 
range through 17 (octal), while later versions can allocate an additional 
number of channels. Also, no arguments could be omitted in the macro call. 

Programs written for use under Version 1 assemble and execute properly 
under Versions 3 and 4 when the ..VI.. macro call is used. The RT-11 overlay 
handler uses Version 1 calls because they take less memory. (See Chapter 11, 
Linker [LINK], of the RT-11 System User's Guide.) The ..VI.. macro call 
causes all Version 1 programmed requests to expand exactly as they did in 
Version 1. However, it is to your advantage to convert Version 1 programs to 
the current format for programmed requests (see Section 2.7). 

1.1.4.2 Version 2 Programmed Requests — The release of RT-11 Version 2 
included new programmed requests and a different way of handling argu- 
ments. The new programmed requests reflected RT-U's ability to run a fore- 
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ground job as well as a background job. They included requests to suspend/re- 
sume the foreground job and to share messages and data between the two 
jobs. 

Arguments in Version 2 programmed requests were stored in an argument 
block instead of on the stack. Another difference in Version 2 was that argu- 
ments could be omitted from macro calls. If the Area argument — that is, the 
pointer to the argument block — was omitted, the macro assumed that RO 
pointed to a valid argument block. If any of the optional arguments were not 
present, the macro placed a zero in the argument block for the corresponding 
argument. Version 1 programmed requests were modified to incorporate these 
changes, and the ..VI.. macro was provided to allow Version 1 programmed 
requests to execute under Version 2 without further modification. 

Programs written for use under Version 2 assemble and execute properly 
under Version 3 and 4 when the ..V2.. macro call is used. The ..V2.. macro call 
causes all programmed requests prior to Version 3 to expand in Version 2 
format. 

1 .1 .4.3 Version 3 Programmed Requests — The programmed requests for Ver- 
sion 3 provide means for user programs to access regions in extended memory 
and to use more than one terminal. The chief difference between Version 2 
and Version 3 programmed requests is the way in which omitted arguments 
are handled. In Version 3 and 4, blank arguments in the macro calls do not 
cause zeros to be entered into the argument block, but leave the corresponding 
argument block entry for the missing argument untouched. 

This change can have a significant impact on user programs. If an argument 
block within a program is to be used many times for similar calls, you can 
save instructions by setting up the argument block entries only once (at 
assembly or run time), and leaving the corresponding fields blank in the 
macro call. 

However, you should keep in mind that you may not substitute zeroes for 
missing fields. Programs written with this assumption operate incorrectly and 
exhibit a wide range of symptoms that can be hard to diagnose. Therefore, you 
must write the necessary instructions to fill the argument block if a pro- 
grammed request is issued with fields left blank in the argument list. 

Programmed requests from previous versions were modified to incorporate 
this change, and the ..V2.. macro call was provided so that Version 2 programs 
could execute properly under Version 3 without further modification. 

1.1.4.4 Version 4 Programmed Requests — Certain programmed requests 
have taken on additional functions to support the system job feature. These 
programmed requests and their additional functions follow: 

Programmed Request Added Function 

.GTJB Returns logical job name. 

.CHCOPY May specify logical job name. 

.LOOKUP Opens message channel to any job; issues 

.READ/CAV, .WRITE/C/W, and .WAIT re- 
quests to communicate between jobs. 
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1.1.5 Programmed Request Conversion 

The previous sections describe the modified format of programmed requests 
that were developed after those of Version 1. This section describes the con- 
version process from the Version 1 format to Version 3. 



1 .1 .5.1 Macro Calls Not Requiring Conversion — Version 1 macro calls that do 
not require any conversion are as follows: 

.CSIGEN .RCTRLO 

.CSISPC .RELEAS 

•DATE .SETTOP (Note 1) 

.DSTATUS .SRESET 

.EXIT .TTINR (Note 2) 

.FETCH .TTOUTR (Note 2) 

.HRESET .TTYIN 

.LOCK .TTYOUT 

.PRINT .UNLOCK 
.QSET 

Note 1: Provided that location 50 is examined for the maximum value. 

Note 2: Except in FB or XM systems. 

1.1.5.2 Macro Calls That Can Be Converted — Version 1 macro calls that can 
be converted are as follows: 

.CLOSE .RENAME 

.DELETE .REOPEN 

.ENTER .SAVESTATUS 

.LOOKUP .WAIT 

.READ .WRITE 

The general format of the ..VL. system macro is 

.PRGREQ Chan,Argl,...,Argn 

In this form, Chan is an integer between and 17 (octal) and is not a general 
assembler argument. The channel number is assembled into the EMT in- 
struction itself. The arguments Argl through Argn are either moved into RO or 
pushed on the stack. 

The ..V2.. equivalent of the above call is 

.PRGREQ Area, Chan, Argl,..., Argn 

In this form, the Chan argument can be any legal assembler argument and 
can be in the range from to 377 (octal). Area points to an argument block 
where the arguments Argl through Argn will be placed. 
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For example, consider a .READ programmed request in both forms: 

Version 1: .READ 5 .»BUFF f «25S . .BLOCK 

Version 2: .READ #AREA t«5 »*BUFF t«25B . .BLOCK 



AREA: .WORD ;CHANNEL/FUNCT ION CODE HERE 
WORD ;BL0CK NUMBER HERE 
WORD ;5UFFER ADDRESS^HERE 

WORD ;A 1 GOES HERE 

Thus, the difference in the two macro calls is that Version 2 declares the 
channel number as a legal assembler argument and adds an Area argument. 

Table 1-3 shows a complete list of conversions for the programmed requests 
that can be converted. Version 1 and Version 2 formats are given. In Version 3, 
this function is performed automatically. The arguments shown inside the 
square brackets ([ ]) are optional. Refer to the appropriate section in Chapter 2 
for more details on each request. 

Table 1-3: Programmed Request Conversions (Version 1 to Version 2) 



Version 


Programmed Request 


VI: 
V2: 


.DELETE chan,dblk 

.DELETE area,chan,dblk[,count] 


VI: 
V2: 


.LOOKUP chan,dblk 
.LOOKUP area,chan,dblk[,count] 


VI: 
V2: 


.ENTER chan,dblk[,length] 

.ENTER area,chan,dblk[,length[,count]l 


VI: 
V2: 


.RENAME chan.dblk 
.RENAME area,chan,dbik 


VI: 
V2: 


.SAVESTAT chan,cblk 
.SAVESTAT area,chan,cblk 


VI: 
V2: 


.REOPEN chan,cblk 
.REOPEN area,chan,cblk 


VI: 
V2: 


.CLOSE Chan 
.CLOSE chan 


VI: 
V2: 


.READ/.READW chan,buff,wcnt,blk 
.READ/.READWarea,chan,buff,wcnt,blk 


VI: 
V2: 


.READC chan,buff,wcnt,crtn,blk 
.READC area,chan,buff,wcnt,crtn,blk 


VI: 
V2: 


.WRITE/.WRITW chan,buff,wcnt,blk 
.WRITE/.WRITWarea,chan,buff,wcnt,blk 


VI: 
V2: 


WRITC chan,buff,wcnt,crtn,blk 
.WRITC area,chan,buff,wcnt,crtn,blk 


VI: 
V2: 


.WAIT chan 
.WAIT chan 
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Several important features of Version 3 calls to be kept in mind when using 
them are as follows: 

1. Version 3 calls require the area argument, which points to the area where 
the other arguments will be (unless RO already points to it and the first 
word is set up). 

2. Enough memory space must be allocated to hold all the required argu- 
ments. 

3. The chan argument must be a legal assembler argument, not just an 
integer between and 17 (octal). 

4. Blank fields are permitted in the Version 3 calls. Any field not specified 
(left blank) is not modified in the argument block. 

1.1.6 Programmed Request Summary 

Many programmed requests operate only in a specific RT-11 environment, 
such as under a foreground/background monitor or when using a special fea- 
ture such as multi-terminal operation. Table 1-4 lists the programmed re- 
quests that can be used in all RT-11 environments, including multi-terminal 
operation. Table 1-5 lists the additional programmed requests that can be 
used under the foreground/background monitor and extended memory moni- 
tor. The EMT and function code for each request are shown in octal. Although 
only the first six characters of the programmed request are significant to the 
Macro assembler, the longer forms are shown to provide a better understand- 
ing of the request function. Also, the purpose of each request is described. 

Macros that are used in interrupt service routines and in writing device han- 
dlers are listed since they are a part of the system macro library. 

Table 1-4 summarizes the programmed requests that work in all RT-11 envi- 
ronments. The programmed requests followed by (MT) work only under the 
multi-terminal feature of RT-11. 

Table 1-4: Programmed Requests for All RT-11 Environments 



Name 



.CDFN 
.CHAIN 
.CLOSE 
.CMKT 

.CSIGEN 

.CSISPC 



EMT 



375 


15 


374 


10 


374 


6 


375 


23 


344 


— 


345 





Code 



Purpose 



Defines additional channels for I/O 

Chains to another program (in background job only) 

Closes the specified channel 

Cancels an unexpired mark time request (special 
feature in single-job environment) 

Calls the Command String Interpreter (CSI) in gen- 
eral mode 

Calls the Command String Interpreter (CSI) in the 
special mode 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments (Cont.) 



Name 



.CTIMIO 

.DATE 

.DELETE 

.DRAST 

.DRBEG 

.DRBOT 

.DRDEF 

.DREND 
.DRFIN 

.DRSET 
.DRVTB 



.DSTATUS 

.ENTER 

.EXIT 

.FETCH 

.FORK 



.GTIM 
.GTJB 
.GTLIN 

GVAL 
.HERR 
.HRESET 



EMT 



374 
375 



342 
375 
350 
343 



Code 



12 




375 


21 


375 


20 


345 


— 


375 


34 


374 


5 


357 


— 



Purpose 



Used within a device handler as a macro call to 
cancel a mark time request (special feature) 

Moves the current date information into RO 

Deletes the file from the specified device 

Used with device handlers to create the asynchro- 
nous entry points to the handler 

Used with device handlers to create a five-word 
header, and .ASECT locations 52 through 60 

Used with system device handlers to set up the pri- 
mary driver 

Used with device handlers to set up handler param- 
eters, call driver macros from the library, and define 
useful symbols 

Used with device handlers to generate the table of 
pointers into the resident monitor 

Used with device handlers to generate the code re- 
quired to exit to the completion code in the resident 
monitor 

Used with device handlers to create or extend the 
list of SET options for a device 

Used with multi-vector device handlers to generate 
a table that contains the vector location, interrupt 
entry point, and processor status word for each de- 
vice vector 

Returns the status of a particular device 

Creates a new file for output 

Exits the user program 

Loads a device handler into memory 

Generates a subroutine call in an interrupt service 
routine that permits long but not critical processing 
to be postponed until all other interrupts are dis- 
missed 

Gets the time of day 

Gets parameters of a job 

Accepts an input line from either an indirect com- 
mand file or from the console terminal 

Returns monitor fixed offsets 

Specifies termination of a job on fatal errors 

Terminates I/O transfers and does a .SRESET oper- 
ation 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments (Cont.) 



Name 



.INTEN 
.LOCK 

.LOOKUP 

.MFPS 
.MRKT 

.MTATCH (MT) 

.MTDTCH (MT) 

.MTGET (MT) 
.MTIN (MT) 

.MTOUT (MT) 

.MTPRNT (MT) 

.MTPS 

.MTRCTO (MT) 
.MTSET (MT) 

.MTSTAT (MT) 
.PRINT 

.PURGE 
.QELDF 

.QSET 
.RCTRLO 



EMT 



346 



375 



375 

375 

375 

375 
375 

375 

375 



375 
375 

375 
351 

374 



353 
355 



Code 



22 

37 

37 

37 
37 

37 

37 



37 

37 

37 



Purpose 



Generates a subroutine call to notify the monitor 
that an interrupt has occurred, requests system 
state, and sets processor priority to the specified 
value 

Makes the monitor User Service Routine (USR) per- 
manently resident until an .EXIT or .UNLOCK is 
executed; the user program is swapped out, if neces- 
sary 

Opens an existing file for input and/or output via 
the specified channel; opens a message channel to a 
specified job 

Reads the priority bits in the processor status word, 
but does not read the condition codes 

Marks time, that is, sets an asynchronous routine to 
be entered after specified interval (special feature in 
single-job environment) 

Attaches a terminal for exclusive use by the request- 
ing job 

Detaches a terminal from one job and frees it for use 
by other jobs 

Returns the status of a specified terminal to the user 

Operates as a .TTYIN request for a multi-terminal 
configuration 

Operates as a .TTYOUT request for a multi-termi- 
nal configuration 

Operates as a .PRINT request for a multi-terminal 
configuration 

Sets the priority bits, condition codes, and T-bit in 
the processor status word 

Resets the CTRL/0 flag for the designated terminal 

Modifies terminal status in a multi-terminal config- 
uration 

Provides multi-terminal system status 

Outputs an ASCII string terminated by a zero byte 
or a 200 byte 

Clears out a channel for reuse 



l->p»l/^ !<>■»• Q +*" 



define offsets in the 



Used with device hanuiers lo 
I/O queue element 

Increases the size of the monitor I/O queue 

Enables output to the terminal, overriding any pre- 
vious CTRL/O 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments (Cont.) 



Name 



.READ 



nwinr 



.READW 

.RELEASE 
.RENAME 

.REOPEN 

.SAVESTATUS 

.SCCA 

.SDTTM 

.SERR 

.SETTOP 

.SFPA 

.SPFUN 

.SRESET 

.SYNCH 

.TIMIO 

.TLOCK 



EMT 



375 



S7.C. 



375 

343 
375 

375 

375 

375 
375 
374 

354 

375 

375 

352 



374 



Code 



10 



in 



10 



6 

5 

35 

40 

4 



30 
32 



Purpose 



Transfers data on the specified channel to a mem- 
ory buffer and returns control to the user program 
when the transfer request is entered in the I/O 
queue; no special action is taken upon completion of 
I/O 

Transfers data on the specified channel to a mem- 
ory buffer and returns control to the user program 
when the transfer request is entered in the I/O 
queue; upon completion of the read, control trans- 
fers asynchronously to the completion routine speci- 
fied in the .READC request 

Transfers data via the specified channel to a mem- 
ory buffer and returns control to the user program 
only after the transfer is complete 

Rem.oves a device handler from memory 

Changes the name of the indicated file to a new 
name; if this request is attempted when using mag- 
tape, the handler returns an illegal operation code 

Restores the parameters stored via a .SAVES- 
TATUS request and reopens the channel for I/O 

Saves the status parameters of an open file in user 
memory and frees the channel for use 

Enables intercept of CTRL/C commands 

Sets the system date and/or time 

Inhibits most fatal errors from aborting the current 
job 

Specifies the highest memory location to be used by 
the user program 

Sets user interrupt for floating-point processor ex- 
ceptions 

Performs special functions on magtape, cassette, 
diskette, and some disk devices 

Resets all channels and releases the device handlers 
from memory 

Generates a subroutine call that enables your pro- 
gram to perform programmed requests from within 

an interrupt service routine 

Generates a subroutine call in a handler to schedule 
a mark time request (special feature in all environ- 
ments) 

Indicates if the USE is currently used by another 
job and performs exactly as a .LOCK request in a 
single-job environment 



(continued on next page) 
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Table 1-4: Programmed Requests for All RT-11 Environments (Cont.) 



Name 



.TRPSET 

.TTINR 
.TTYIN 

-TTYOUT 
.TTOUTR 

.UNLOCK 

..VI.. 
..V2.. 
.WAIT 

.WRITC 



EMT 



.WRITE 



.WRITW 



375 
340 
341 
347 



Code 



374 
375 



375 



375 



Purpose 



11 



11 



11 



Sets a user intercept for traps to monitor locations 4 
and 10 

Reads none character from the keyboard buffer 



Transfers none character to the terminal input 
buffer 

Releases the USR after execution of a .LOCK and 
swaps in the user program, if required 

Provides compatibility with Version 1 format 

Provides compatibility with Version 2 format 

Waits for completion of all I/O on a specified chan- 
nel 

Transfers data on the specified channel to a device 
and returns control to the user program when the 
transfer request is entered in the I/O queue; upon 
completion of the write, control transfers asynchro- 
nously to the completion routine specified in the 
.WRITC request 

Transfers data on the specified channel to a device 
and returns control to the user program when the 
transfer request is entered in the I/O queue; no spe- 
cial action is taken upon completion of the I/O 

Transfers data on the specified channel to a device 
and returns control to the user program only after 
the transfer is complete 



Table 1-5 lists the additional programmed requests that can be used only in a 
foreground/background and extended memory environment. The programmed 
requests followed by XM in parentheses ((XM)) operate only in an extended 
memory environment. 

Table 1-5: Foreground/Background and Extended Memory 
Programmed Requests 



Name 



.CHCOPY 
.CNTXSW 

.CRAW (XM) 
.CRRG (XM) 
.CSTAT 



EMT 



375 
375 

375 
375 
375 



Code 



13 
33 

36 
36 
27 



Purpose 



Allows one job to access another job's channel 

Requests that the indicated memory locations be 
part of FB context switch process 

Creates a window in virtual memory 

Creates a region in extended memory 

Returns the status of the channel indicated 



(continued on next page) 
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Table 1-5: Foreground/Background and Extended Memory 
Programmed Requests (Cont.) 



Name 



.DEVICE 

.ELAW (XM) 
.ELRG (XM) 
.GMCX (XM) 
.MAP (XM) 
.MWAIT 
.PROTECT 

.RCVD 

.RCVDC 

.RCVDW 

.RDBBK (XM) 

.RDBDF (XM) 

.RSUM 

.SDAT 

.SDATC 

.SDATW 

.SPCPS 

.SPND 
.TWAIT 

.UNMAP (XM) 
.UNPROTECT 
.WDBBK (XM) 

.WDBDF (XM) 



EMT 



375 

375 
375 
375 
375 
374 
375 

375 



374 
375 

375 

374 
375 

375 
375 



Code 



14 

36 
36 
36 
36 
11 
31 

26 



2 
25 

41 

1 
24 

36 

31 



Purpose 



Allows device interrupts in FB to be disabled upon 
program termination 

Eliminates an address window in virtual memory 

Eliminates an allocated region in extended memory 

Returns mapping status of a specified window 

Maps a virtual address window to extended memory 

Waits for messages to be processed 

Requests that specified vectors in the area from to 
476 be given exclusively to the current job 

Receives data — allows a job to read messages or 
data sent by another job in an FB environment. The 
three modes correspond to the .READ, .READC, 
and .READW requests 

Reserves space in a program for a region definition 
block and sets up the region size and region status 
word 

Defines the offsets and bit names associated with a 
region definition block 

Causes the mainline code of the job to be resumed 
after it was suspended by a .SPND request 

Sends messages or data to the other job in an FB 
environment. The three modes correspond to the 
.WRITE, .WRITC, and .WRITW requests 

Used in a completion routine to change the flow of 

Causes the running job to be suspended 

Suspends the running job for a specified amount of 
time 

Unmaps a virtual address memory window 

Cancels the .PROTECT vector protection request 

Reserves space in a program for a window definition 
block and sets up the associated data 

Defines the offsets and bit names associated with a 
window definition block 



1.2 Using the bystem suoroutine Liorary 

The system subroutine library is a collection of FORTRAN-callable routines 
that allow various RT-11 system features to be used by a FORTRAN pro- 
grammer. There are no FORTRAN routines to manipulate extended memory 
under the extended memory (XM) monitor. 
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This collection of subroutines is placed in a system library called 
SYSLIB.OBJ. This library file also contains the overlay handlers, utility func- 
tions, a character string manipulation package, and two-word integer support 
routines. The linker uses this library to resolve undefined globals. It is resi- 
dent on the system device (SY:). 

You should be familiar with the PDP-11 FORTRAN Language Reference 
Manual and the RT-11/RSTS/E FORTRAN IV User's Guide before using the 
material in this chapter. 

The system subroutine library provides the following capabilities: 

1. Complete RT-11 I/O facilities, including synchronous, asynchronous, and 
event-driven modes of operation. FORTRAN subroutines can be activated 
upon completion of an input/output operation. 

2. Timed scheduling of completion routines. This feature is standard in the 
FB and XM monitors, and is a special feature in the SJ monitor. 

3. Facilities for communication between foreground and background jobs. 

4. FORTRAN language interrupt service routines for user devices. 

5. Complete timer support facilities, including timed suspension of execution 
in a FB or XM environment, conversion of different time formats, and 
time-of-day information. The timer support facilities can use either 50- or 
60-cycle clocks. 

6. All RT-11 auxiliary input/output functions, including the capabilities of 
opening, closing, renaming, and creating or deleting files on any device. 

7. All monitor-level information functions, such as job partition parameters, 
device statistics, and input/output channel statistics. 

8._ Access to the RT-11 command string interpreter (CSI). 

9. A character string manipulation package supporting variable-length char- 
acter strings. 

10. INTEGER*4 support routines that allow two-word integer computations. 



NOTE 

When variables are described or mentioned, and unless other- 
wise specified, INTEGER means INTEGER*2, (16-bit integer) 
and REAL means REAL*4 (single-precision floating point). In- 
teger and real arguments to subprograms are indicated in this 
section as follows: 



i = INTEGER*2 arguments 
j = INTEGER* 4 arguments 
a= REAL*4 arguments 
d= REAL*8 arguments 
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In general, the routines in SYSLIB were written for use with RT-11 V2 or later 
and FORTRAN IV VlB or later versions. The use of SYSLIB with prior 
versions of RT-11 or FORTRAN may lead to unpredictable results. 

1.2.1 System Conventions 

This section describes system conventions that must be followed for proper 
operation of calls to the system subroutine library. Certain restrictions that 
apply are described in Section 1.2.1.7. 

1 .2.1 .1 Channel Numbers — A cnannel numoer is a logicai laenuiier lor a me 
or for a set of data used by FORTRAN. Thus, when you open a file on a 
particular device, you assign a channel number to that file. To refer to an 
open file, it is only necessary to refer to the appropriate channel number. 

The FORTRAN system has 16(decimal) channels available for your use. The 
call IGETC assigns a channel to your program and notifies the FORTRAN I/O 
system, which also uses these channels, that the channel is in use. When there 
is no longer need for a channel, the program should close the channel with a 
CLOSEC, ICLOSE or a PURGE SYSLIB call. The channel should be freed 
and returned to the FORTRAN I/O system with a IFREEC call. 

Up to 255{decimal) channels can be activated with the ICDFN call. This 
function sets aside memory in the job area to accommodate status informa- 
tion for the extra channels. Use the ICDFN call during the initialization phase 
of your program. You can use ail channels numbered higher than 15(decimal). 
The FORTRAN I/O system uses channels through 15(decimal). 

Channels must be allocated in the main program routine or its subprograms. 
Do not allocate channels in routines that are activated as the result of I/O 
completion events or ISCHED or ITIMER calls. 

1.2.1.2 Completion Routines — Completion routines can be written in FOR- 
TRAN or assembly language, depending upon the function called. 

A completion routine is a subprogram that executes asynchronously with a 
main program and is scheduled to run as soon as possible after the completion 
of an associated event, such as an I/O transfer or the passing of a specified 
time interval. All completion routines of the current job have higher priority 
than other parts of the job. Therefore, once a completion routine becomes 
runnable because of its associated event, it interrupts execution of the job and 
continues to execute until it relinquishes control. 

Completion routines are handled differently in the SJ and the FB and XM 
monitors. In the SJ monitor, these routines are totally asynchronous and can 
interrupt one another. In the FB and XM monitors, completion routines do 

is running. They are then scheduled on a first-in, first-out basis. 

Assembly language completion routines exit with an RTS PC instruction. 
FORTRAN completion routines exit by the execution of a RETURN or END 
statement in the subroutine. All names of completion routines external to the 
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routine being coded that are passed to scheduling calls must be specified in an 
EXTERNAL statement in the FORTRAN program unit issuing the call. 

A completion routine written in FORTRAN can have a maximum of two 
arguments as follows: 

Form: SUBROUTINE crtn [(iargl,iarg2)] 

where: 

crtn is the name of the completion routine 

iargl is equivalent to RO on entry to an assembly language comple- 
tion routine 

iarg2 is equivalent to Rl on entry to an assembly language comple- 
tion routine 

If an error occurs in a completion routine or in a subroutine at completion 
level, the error handler traces back through to the original interruption of the 
main program. Thus, the traceback is shown as though the completion routine 
were called from the main program. This lets you know where the main 
program was executing, so that when an error is fatal, it can be diagnosed and 
corrected. 

Certain restrictions apply to completion routines that are activated by the 
following calls: 



INTSET 


ISDATF 


IRCVDC 


ISPFNC 


IRCVDF 


ISPFNF 


IREADC 


ITIMER 


IREADF 


IWRITC 


ISCHED 


IWRITF 


ISDATC 


MRKT 



The restrictions that apply when using these calls are as follows: 

• No channels can be allocated by calls to IGETC or freed by calls to IFREEC 
from a completion routine. Channels to be used by completion routines 
should be allocated and placed in a COMMON block for use by the routine. 

• The completion routine cannot perform any call that requires the use of the 
USR, such as LOOKUP and lENTER. See section 1.2.1.5 for a list of the 
SYSLIB functions that call the USR. 

• Files that are used by the completion routine must be opened and closed by 
the main program. There are, however, no restrictions on the input or out- 
put operations that can be performed in the completion routine. If many 
files must be made available to the completion routine, they can be opened 
by the main program and saved for later use (without tying up RT-11 
channels) by an ISAVES call. The completion routine can later make them 
available by reattaching the file to a channel with an IREOPN call. 

Even if the completion routine itself does not issue any programmed re- 
quests, but does perform I/O to a logical unit number through the OTS, that 
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logical unit number must be opened from the main level. To accomplish 
this, either the first I/O access or an OPEN statement must be issued from 
main level. A completion routine may not call CLOSE to close a logical 
unit. 

FORTRAN subroutines are reusable but not reentrant. That is, a given 
subroutine can be used many times as a completion routine or as a routine 
in the main program, but a subroutine executing as main program code does 
not work properly if it is interrupted and then called again at the comple- 
tion level. This restriction apphes to all subroutines that can be invoked at 
the completion level while they are active in the main program. 

Under the SJ monitor, only one completion function should be active at any 
time. 



1.2.1.3 Device Blocks — A device block is a four-word block of RAD50 infor- 
mation that specifies a physical device and a file name. In FORTRAN, you 
can use one of three different methods to set up this block as follows: 

1. You can use the DIMENSION and DATA statements. For example, 

DIMENSION IFILE (4) 

DATA IFILE/3RBY ,3RFIL.3RE ,3RKYZ/ 

2. You can translate the available ASCII file description string into RAD50 
format, using the SYSLIB calls IRAD50, R50ASC, and RAD50. For 
example, 

r'eal*b fspec 

CALL IRAD50 ( 12 t 'SY FILE KYZ'tFSPEC) 

3. You can use the SYSLIB call ICSI to call the Command String Interpreter 
(CSI) to accept and parse standard RT-11 command strings. 

1 .2.1 .4 INTEGER*4 Support Functions — This section discusses the initializa- 
tion of INTEGER*4 variables for the FORTRAN programmer. Section 1.2.6.3 
describes the use of INTEGER*4 functions for use by the MACRO program- 
mer. 

When the DATA statement is used to initialize INTEGER*4 variables, it 
must specify both the low- and high-order parts. For example, the code 

INTEGER#4 J 
DATA J/3/ 

Initializes only the first word. The correct way to initialize an INTEGER*4 
variable to a constant such as 3 is as follows: 

INTEGER*4 J 

INTEGER*2 liZ) 

EQUIVALENCE (Jfl) 

DATA 1/3.0/ ! INITIALIZE J TO 3 
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If you are initializing an INTEGER*4 variable to a negati- 
the high-order (second word) part must be the continuatic 
plement of the low-order part. For example, 



INTEGER*a J 
INTEGER*2 1(2) 
EQUIUALENCE (J 
DATA I/-4J-1/ 



I ) 



! INITIALIZE J TO -4 



The following example is suitable for initializing INTEG: 
subprograms: 



INTEGER*2 J(2) 
DATA J/3 ,0/ 



!LOW ORDER fHIGH ORDER 



1.2.1.5 User Service Routine (USR) Requirements — Us 

that interface to the FORTRAN Object Time System (OTJ 
the location of the RT-11 User Service Routine (USR). Th 
words. When your program calls a SYSLIB routine the 
function (such as lENTER or LOOKUP), or when the USl 
FORTRAN OTS, the USR is swapped into memory if it i 
FORTRAN OTS is designed so that the USR can swap o^ 

If you permit the USR to swap over certain kinds of data 
obtain unpredictable results. In particular, you should res 
vice routines and completion routines to locations outside 
area. To find the limits of this swapping area, examine th 
necessary, change the order of object modules and libraries 
Linker. 

Subroutines that require the USR are as follows: 

CLOSECICLOSE 

GETSTR (only if first I/O operation on logical uni; 

ICDFN (single job only) 

GTLIN 

ICSI 

IDELET 

IDSTAT 

lENTER 

IFETCH 

IQSET 

IRENAM 

ITLOCK 

LOCK 

LOOKUP 

PUTSTR (only if first I/O operation on logical unit 

CONTROLLING USR SWAPPING 

You can control USR swapping by using the KMON com 
NOSWAP and SET USR SWAP. The SET USR NOSW. 
vents swapping and freezes the USR in memory just below 
tor or the foreground job. The command SET USR S\\ 
allowing the USR to swap under program control. 



(only if USR is not in use by the other jo 
(only if USR is in a swapping state) 
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logical unit number must be opened from the main level. To accomplish 
this, either the first I/O access or an OPEN statement must be issued from 
main level. A completion routine may not call CLOSE to close a logical 
unit. 

• FORTRAN subroutines are reusable but not reentrant. That is, a given 
subroutine can be used many times as a completion routine or as a routine 
in the main program, but a subroutine executing as main program code does 
not work properly if it is interrupted and then called again at the comple- 
tion level. This restriction applies to all subroutines that can be invoked at 
the completion level while they are active in the main program. 

• Under the SJ monitor, only one completion function should be active at any 
time. 



1 .2.1 .3 Device Blocks — A device block is a four-word block of RAD50 infor- 
mation that specifies a physical device and a file name. In FORTRAN, you 
can use one of three different methods to set up this block as follows: 

1. You can use the DIMENSION and DATA statements. For example, 

DIMENSION IFILE (4) 

DATA IFILE/3RSY ,3RFIL,3RE ,3RXYZ/ 

2. You can translate the available ASCII file description string into RAD50 
format, using the SYSLIB calls IRAD50, P^OASC, and RAD50. For 
example, 

REAL*S FSPEC 

CALL IRAD50 ( 12 . 'BY FILE KYZ ' , FSPEC) 

3. You can use the SYSLIB call ICSI to call the Command String Interpreter 
(CSI) to accept and parse standard RT-U command strings. 



1 .2.1 .4 INTEGER*4 Support Functions — This section discusses the initializa- 
tion of INTEGERS variables for the FORTRAN programmer. Section 1.2.6.3 
describes the use of INTEGER*4 functions for use by the MACRO program- 
mer. 

When the DATA statement is used to initialize INTEGER*4 variables, it 
must specify both the low- and high-order parts. For example, the code 

INTEGER*^ J 
DATA J/3/ 

Initializes only the first word. The correct way to initialize an INTEGER*4 
variable to a constant such as 3 is as follows: 

INTEGER*il J 

INTEGER*2 1(2) 

EQUIVALENCE (J»I) 

DATA 1/3,0/ ! INITIALIZE J TO 3 
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If you are initializing an INTEGER*4 variable to a negative value such as -4, 
the high-order (second word) part must be the continuation of the two's com- 
plement of the low-order part. For example, 



INTEGER#4 J 

INTEGER*2 1(2) 

EQUIVALENCE (J, I) 

DATA I/-4,-l/ ilNITIALIZE J TO -4 

The following example is suitable for initializing INTEGER*4 arguments to 
subprograms: 

INTEGER*2 J(2) 

DATA J/3.0/ !LQW ORDER, HIGH ORDER 

1.2.1.5 User Service Routine (USR) Requirements — User-written routines 
that interface to the FORTRAN Object Time System (OTS) must account for 
the location of the RT-11 User Service Routine (USR). The USR occupies 2K 
words. When your program calls a SYSLIB routine that requests a USR 
function (such as lENTER or LOOKUP), or when the USR is invoked by the 
FORTRAN OTS, the USR is swapped into memory if it is nonresident. The 
FORTRAN OTS is designed so that the USR can swap over it. 

If you permit the USR to swap over certain kinds of data and code, you will 
obtain unpredictable results. In particular, you should restrict interrupt ser- 
vice routines and completion routines to locations outside the USR swapping 
area. To find the limits of this swapping area, examine the link map and, if 
necessary, change the order of object modules and libraries as specified to the 
Linker. 

Subroutines that require the USR are as follows: 

CLOSECICLOSE 

GETSTR (only if first I/O operation on logical unit) 

ICDFN (single job only) 

GTLIN 

ICSI 

IDELET 

IDSTAT 

lENTER 

IFETCH 

IQSET 

IRENAM 

ITLOCK (only if USR is not in use by the other job) 

LOCK (only if USR is in a swapping state) 

LOOKUP 

PUTSTR (only if first I/O operation on logical unit) 

CONTROLLING USR SWAPPING 

You can control USR swapping by using the KMON commands SET USR 
NOSWAP and SET USR SWAP. The SET USR NOSWAP command pre- 
vents swapping and freezes the USR in memory just below the resident moni- 
tor or the foreground job. The command SET USR SWAP reverses this, 
allowing the USR to swap under program control. 
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Alternatively, you can compile your FORTRAN main program with the 
/NOSWAP option in order to be sure that there is space just below the fore- 
ground partition or RMON to make the USR permanent for the duration of 
your program. Use this option if your program does not need the 2K words of 
memory that the USR occupies. If the /NOSWAP option is not specified, the 
USR swaps over the 2K words of your program above the base 
address — that is, from location lOOO(octal) to llOOO(octal), which is the part 
of a FORTRAN program least likely to violate the USR restrictions. 

To prevent USR swapping for part of the program execution time and allow 
me usrt to swap out at otner times, use uie ukjk^i:^, uim^v^^^i^, anu ii±jv^v^i>. 
calls. 

The LOCK call locks the USR into main memory and attaches it to the 
requesting job. The UNLOCK call allows the USR to swap again and to be 
used by another job. The ITLOCK call is used to determine whether another 
job is already using the USR. If so, the ITLOCK call returns immediately 
with an error code. This allows the program to try for a lock, but to continue 
with other action if it fails. The LOCK and UNLOCK calls are used in a 
foreground program to prevent interference from the background during ini- 
tialization and completion phases and to minimize the number of swaps. 

STRATEGIES IN USR SWAPPING 

If you decide to change the position of code or data to avoid the USR swap- 
ping area, or if you want to move the USR itself, you must consider the 
concept of PSECT (program section) ordering. 

PSECTs contain code and data and are identified by unique names as seg- 
ments of the object program. The attributes associated with each PSECT 
direct the Linker to combine several separately compiled FORTRAN program 
units, assembly language modules, and library routines into an executable 
program. 

1 ne uruer in wilicil prugram scununs are aiiuuateu 111 tiic CAci^uLduic pn->giciiii 

is the order that they are presented to the Linker. AppHcations that are 
sensitive to this ordering typically separate those sections containing read- 
only information (such as executable code and pure data) from impure sec- 
tions containing variables. 

The main program unit of a FORTRAN program (normally the first object 
module in sequence presented to LINK) declares PSECT ordering as shown in 
Table 1-6. 

Table 1-6: FORTRAN Program PSECT Ordering 



Section Name 


Attributes 


OTSSI 
OTS$P 
SYS$I 
USERS! 


RW,I,LCL,REL,CON 
RW,D,GBL,REL,OVR 
RW,I,LCL,REL,CON 
RW,I,LCL,REL,CON 



(continued on next page) 
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Table 1-6: FORTRAN Program PSECT Ordering (Cont.) 



Section Name 


Attributes 


$CODE 


RW,I,LCL,REL,CON 


OTS$0 


RW,I,LCL,REL,CON 


SYS$0 


RW,I,LCL,REL,CON 


$DATAP 


RW,D,LCL,REL,CON 


OTS$D 


RW,D,LCL,REL,CON 


OTS$S 


RW,D,LCL,REL,CON 


SYS$S 


RW,D,LCL,REL,CON 


$DATA 


RW.D,LCL,REL,CON 


USER$D 


RW,D,LCL,REL,CON 


.$$$$. 


RW,D,GBL,REL,OVR 


Other COMMON Blocks 


RW,D,GBL,REL,OVR 



The USR can swap over pure code, but must not be loaded over constants or 
impure data that can be used as arguments to the USR. The ordering shown 
in Table 1-6 collects all pure sections before impure data in memory. The 
USR can safely swap over sections OTS$I, OTS$P, SYS$I, USER$I, and 
$CODE. The default is to swap at the base of section OTS$I. Location 46 of 
the System Communication Area contains the address where the USR will 
swap. If location 46 is zero, the USR will swap at its default location. 

See the RT-11/RSTS/E FORTRAN IV User's Guide for more information on 
program sections. The RT-11 Software Support Manual also contains infor- 
mation on USR swapping and PSECT ordering. 

USR LOCKOUT AND TIMING 

If one job is using the USR and another job requests it, the second job will 
become blocked until the first job releases the USR. The second job may be 
locked out for seconds or minutes at a time. Interrupt service and completion 
routines can run, but not the mainline code. The timing problems that arise 
as a result can be eliminated, or minimized, in one of the following four ways: 

1. Do not use devices with slow directory operations, such as cassettes and 
magtapes. 

2. Code real-time operations as completion and interrupt service routines in 
your foreground job so that a locked out mainline program does not im- 
pact real-time operations. 

3. Separate USR and real-time operations. 

4. Use the ITLOCK call and avoid SYSLIB calls that request the USR while 
the USR is owned by another job. 

Typically, a real-time foreground job can be constructed of (1) an initializa- 
tion phase that opens all required channels and begins a real-time operation, 

(2) a real-time phase that performs interrupt service and I/O operations, and 

(3) a completion phase that halts real-time activity and then closes the chan- 
nels. Maintaining this structure in the foreground allows the background task 
to do USR operations during the real-time phase without locking out the 
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foreground. This also simplifies USR swapping since the USR can swap over 
the interrupt routines and I/O buffers as long as they are inactive. 

1.2.1.6 Subroutines Requiring Additional Queue Elements — Certain 
subroutines require queue elements for their proper operation. These 
subroutines are as follows: 

IRCVD/IRCVDC/IRCVDF/IRCVDW 
IREAD/IREADC/IREADF/IREADW 
ISCHED 

ISLEEP 

ISPFN/ISPFNCASPFNFASPFNW 

ITIMER 

ITWAIT 

lUNTIL 

IWRITC/IWRITE/IWRITF/IWRITW 

MRKT 
MWAIT 

One queue element per job is automatically allocated. Issuing more than one 
request from the Hst requires extra queue elements. Additional queue ele- 
ments can be allocated through a call to the IQSET function. 

1.2.1.7 System Restriction — The following restrictions must be considered 
when coding a FORTRAN program that uses SYSLIB. 

1. Programs using IPEEK, IPOKE, IPEEKB, IPOKEB, or ISPY to access 
system-specific addresses, such as FORTRAN, monitor, or hardware ad- 
dresses, are not guaranteed to run under future releases or on different 
configurations. When using these functions, you should document their 
use precisely so that you can check your references against the current 
documentation. Also, these routines may act differently under the XM 
monitor. 

2. Various functions in SYSLIB return values that are of type integer, real, 
and double precision. If you specify an implicit statement that changes 
the defaults for external function types, you must explicitly declare the 
type of those SYSLIB functions that return integer or real results. You 
must also be sure that the arguments to the SYSLIB routines are the 
correct type for the routine. Double-precision functions must always be 
declared to be type DOUBLE PRECISION (or REAL*8). Failure to ob- 
serve this restriction leads to unpredictable results. 

3 All names of completion routines external to the routine being coded that 
are passed to scheduling calls (such as ISCHED, ITIMER, and IREADC) 
must be specified in an EXTERNAL statement in the FORTRAN pro- 
gram issuing the call. 

4. Certain arguments to SYSLIB calls must be located in such a manner as 
to prohibit the RT-11 User Service Routine (USR) from swapping over 
them at execution time. This kind of swapping can occur when the OTS$I 
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section (which contains the all-pure code and data for the module) is less 
than 2K words in length. Swapping in this uncommon situation can be 
avoided either by typing the SET USR NOSWAP command to make the 
USR resident before starting the job, or by compiling the mainline routine 
with a /NOSWAP option. You can also use the linker /BOUNDARY op- 
tion to make OTS$0 start at word boundary llOOO(octal). (This problem 
generally occurs only with small FORTRAN programs.) 

In FORTRAN IV, program sections (PSECTs) are used to collect code and 
data into appropriate areas of memory. If the RT-11 USR is needed and is 
not resident, it swaps over a FORTRAN program starting at the symbol 
OTS$I for 2K words of memory. 

5. Certain restrictions apply when using completion or interrupt routines. 
See Section 1.2.1.2 for a description of these restrictions. 

6. Unless explicitly stated, null arguments should not be used in calls to 
SYSLIB routines. 

7. If several arguments to a call are listed as being optional, they must either 
be all present or all omitted. 



1.2.2 Calling SYSLIB Subroutines 

SYSLIB includes both function subprograms and callable subroutines, which 
are called in the same manner as user-written subroutines. 

Function subprograms receive control by means of a function reference as 
follows: 

i = function name ([arguments]) 

The returned function value may be an error code, or it may be information 
that is useful to the calling routine. See the description of the particular 
function for the meaning of the returned function value. 

Call subroutines are invoked by means of a CALL statement as follows: 

CALL subroutine name [(arguments)] 

AH subroutines in SYSLIB can be called as FUNCTION programs if a return 
value is desired, or as SUBROUTINE programs if no return value is desired. 
For example, the LOCK subroutine can be referenced as either 

CALL LOCK 



or 



LOCK( ) 



Some subroutines have two acceptable formats. For example, the subroutine 
CLOSEC can also be specified as ICLOSE because error codes have been 
added to the subroutine and require an integer return to be useful. 
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Quoted-string literals are useful as arguments of calls to routines in SYSLIB, 
notably the character string routines. These literals are allowed in subroutine 
and function calls (see Section 3.7.3). 

1.2.3 FORTRAN/MACRO Interface 

FORTRAN calling routines and subroutines follow a well-defined set of con- 
ventions regarding transfer of control, transfer of information, memory usage, 
and register usage. By adhering to these conventions a MACRO programmer 
can write FORTRAN-callable routines such as those in SYSLIB. 

Control is transferred to a subroutine by 

JSR PC fSUBR 

When control passes to the subroutine SUBR, Register 5 (R5) points to an 
argument block that has the format shown in Figure 1-5. 

Figure 1-5: Subroutine Argument Block 



R5=> 



No. of 
arguments 



Address of Argument 1 



Address of Argument 2 



Address of Argument n 



Null arguments in CALL statements must be entered with successive com- 
mas, for example, CALL SUBR (A,,B). The value -1 is stored in the argument 
block as the address of a null argument. 

The lower byte of the first word of the argument block contains the number of 
arguments that are passed to the subroutine. The rest of the argument block 
contains the addresses of those arguments. The argument block is n-i-1 words 
long for n arguments. 

The program counter is the linkage register. The subroutine obtains its 
arguments through R5. In FORTRAN, the calling program saves the registers, 
and the subroutine leaves the contents of the stack pointer intact before 
returning to the calling program. The RETURN statement of the subroutine is 
replaced by 

RTB PC 
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The name of the subroutine must be declared global with the .GLOBL direc- 
tive in the calling program or with the double colon (::) construction in the 
called program. 

NOTE 

You must make sure that the called program does not modify 
the argument block passed by the calling program to a sub- 
program. 

1.2.3.1 Subroutine Register Usage — A subroutine that is called by a FOR- 
TRAN program does not have to preserve any registers. However, each push 
onto the stack must be matched by a pop off the stack before exiting from the 
routine. 

User-written assembly language programs must preserve any pertinent regis- 
ters before calling FORTRAN subprograms or SYSLIB routines. They must 
then restore registers, if necessary, after the subroutine returns. 

Function subroutines return a single result in a register. Table 1-7 shows the 
register assignments for returning the different variable types. 

Table 1-7: Return Value Conventions for Function Subroutines 



Type 


Result Placed In 


INTEGER*2 
LOGICAL*! 

INTEGER*4 
L0GICAL*4 

REAL 

DOUBLE PRECISION 

COMPLEX 


RO 

RO low-order result 
Rl high-order result 

RO high-order result (including sign and exponent) 
R! low-order result 

RO highest-order result (including sign and exponent) 
Rl next higher order 
R2 next higher order 
R3 lowest-order result 

RO high-order real result 
Rl low-order real result 
R2 high-order imaginary result 
R3 low-order imaginary result 



Note that floating-point results are returned in the general purpose registers 
and not in the FPU registers. Assembly language subprograms that use the 
FPU Floating Point Unit may be required to save and restore the FPU status. 



1.2.3.2 FORTRAN Programs Calling MACRO Subroutines — FORTRAN pro- 
grams can call MACRO subroutines, but several rules must be followed. For 
example, the following program named INIARR is a MACRO subroutine that 
can be called from a FORTRAN program. 



1-46 Introduction to Advanced Rl'-U Programming 





.TITLE 


INIARR 




.GLOBL 


INIARR 


; 


FILENAME INIARR. MAC 


INIARR: 


TST 


(R5) + 




Moy 


(R5) + »R2 




Moy 


@(R5) + .Rl 




MO 1,1 


@t;R5)+ ,R0 




BLE 


RETURN 


1$: 


MG>,i 


Rl »(RZ)+ 




DEC 


RO 




BNE 


1$ 


RETURN: 


RTS 
.END 


PC 



;SKIP ARGUMENT COUNT 
;PUT ADDRESS OF ARRAY 
;PUT Ii.'AL IN Rl 
;AND COUNT INTO RO 
;OUIT IF COUNT IS NOT 
; INITIALIZE ARRAY 
SDECREMENT COUNT 
; CONTINUE UNTIL ZERO 



INTO R2 



POSITIVE 



A FORTRAN program calls the preceding routine with 

CALL INIARR (IAR,IVAL,N) 
where : 

INIARR is the name of the subroutine 

lAR is the name of the array to initialize 

IV AL is the value the array is initialized to 

N is the number of elements to initialize 

This program illustrates the rules that must be observed when calling a 
MACRO program. The name of the subroutine is made global by using the 
.GLOBL directive. 

Register 5 (R5) is used to pass the arguments. Thus, in the program INIARR, 
the argument block would appear as shown in Figure 1-6. 

Figure 1-6: Argument Block for Program INIARR 



R5=> 






3 


Address of lAR 




Address of IVAL 


Address of N 

,._ ^ 



Registers RO through R4 can be freely used since the calling program saves 
them. Once the arguments are retrieved, you can also use R5. 
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On completion, the subroutine returns to the calling program through an RTS 
PC. If your MACRO program pushes data on the stack, you must make sure 
that all data is popped off the stack before the RTS PC is executed. 

The following FORTRAN program named DOFOR calls the subroutine 
INIARR. 

PROGRAH DOFQR 
C 

INTEGER«2 ARRAY 

DIMENSION ARRAY ( 10) 

N = Z 

DO 20 IMAL=1 *10 

CALL INIARR ( ARRAY , I OAL ,N ) 

WRITE (5,100) C ARRAY( I ) ,1 = 1 ,N) 
20 CONTINUE 
100 FORMAT (13) 

STOP 

END 

After you compile and link both programs, run the program by typing 

.RUN DOFOR m 

The initialized array will be output to the terminal as follows: 



3 
4 

a 

5 

5 

B 

G 

7 

7 

8 

8 

9 

3 

10 

10 

STOF 



1.2.3.3 Macro Routines Caiiing FORTRAN Programs — If you want to call 
FORTRAN subroutines from a MACRO program, create a dummy main pro- 
gram such as 



PROGRAM FORINT 
CALL CALMAC 
STOP 
END 
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where CALMAC is the name of a MACRO program that can call FORTRAN 
or MACRO routines. 

Creating a dummy program causes the FORTRAN main program to perform 
the initialization necessary for FORTRAN subroutines. 

The following MACRO program named CALMAC calls a FORTRAN subrou- 
tine named MAXMIN. 





.TITLE 


CALMAC 




. GLOBL 


MAXMIN 


CALMAC: 


; 






MOU 


«ARGBLK .R5 




JSR 


.PC (MAXMIN 




RTB PC 




I : 


.WORD 


28. 


J: 


.WORD 


7G. 


ARGBLK: 


.WORD 


2 




.WORD 


I 




.WORD 


J 




.END 





;point r5 to argument block 
;call maxmin 

;mallie of first argument 
;ualue of second argument 
;number of arguments 
iaddress of first argument 
^address of second argument 



You must set up the argument block either on the stack or in a separate area 
in your MACRO program. You then point R5 to the top of the argument block 
prior to calling the FORTRAN subroutine with a JSR PC, MAXMIN. In the 
above program, the argument block is set up in an area of your program. 

The following program named STAKEM performs the same operation as the 
program CALMAC, except that it places the arguments on the stack. 





.TITLE 


STAKEM 




, GLOBL 


MAXMIN .STAKEM 


STAKEM: 


MOU 


«J ,- (SP) 




HOU 


«I .-(SP) 




MOU 


#2 t-(SP) 




MOU 


SP .R5 




JSR 


PC .MAXMIN 




ADD 


#G.SP 




RTS 


PC 


I: 


.WORD 


28. 


J: 


.WORD 
.END 


76. 



If the argument block is set up on the stack, be sure that you remove the 
arguments from the stack prior to the execution of the RTS PC. In general, 
before calling the FORTRAN subroutine, you must save all pertinent regis- 
ters. You do not know which registers the FORTRAN subroutine is using. The 
contents of the stack pointer remain unchanged across the call. 

The nam_e of the FORTRAN subroutine that the MACRO program, calls m_ust 
be defined as a global. In the FORTRAN subroutine, execute normal FOR- 
TRAN statements and return to the MACRO program with a RETURN state- 
ment. 
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The following program is the FORTRAN subroutine MAXMIN. 

SUBROUTINE MAXH IN ( I N 1 . 1 N2 ) 

INTEGER BIGtSMALL 

IF { INI ,LT, INZ) GO TO 10 

BIG=IN1 

SHALL=IN2 

TYPE 20 .BIG 

TYPE 30. SMALL 

RETURN 
10 BIG=IN2 

SMALL=IN1 

TYPE 20. BIG 

TYPE 30 .SMALL 
20 FORMAT (' THE BIGGER NUMBER IS ',12) 
30 FORMAT (' THE SMALLER NUMBER IS '.12) 

RETURN 

END 

After assembling and linking the programs, using either the program 
CALMAC or STAKEM, type 

.RUN FOR I NT m 

The program executes as follows: 

THE BIGGER NO. IS 7E 
THE SMALLER NO. IS 28 
STOP -- 

1.2.4 FORTRAN Programs in a Foreground/Background 
Environment 

FORTRAN programs can be run in a foreground/background environment, 
which permits efficient use of CPU execution time. (See Chapter 15 oi Intro- 
duction to RT-11 for a description of running in an FB environment.) The 
basic steps in running FORTRAN programs that use the FB monitor are 
described in this section. 

Before running your foreground program, you must use the LOAD command 
to load the device handlers required by the foreground job. The device 
handlers are placed in memory between RMON and the USR and KMON, 
which causes USR and KMON to move down in memory. 

Next, you use the FRUN command to load your foreground program in mem- 
ory between the device handlers and the USR, which causes the USR and 
KMON to move further down in memory. It is important that you allocate 
workspace when running a FORTRAN program in the foreground. You do this 
with the /BUFFER:n option of the FRUN command. Also make sure that any 
FORTRAN program you run in the foreground has adequate stack space. You 
can use one of the options supported by the linker (see the RT-11 System 
User's Guide). 

The background area must be at least 4K words long to accommodate the 
USR and KMON. Until you run a background job with the RUN command, 
KMON is the background job. 
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When the USR is required, a 2K-word area must be set up in each job for the 
swapping to occur correctly — that is, there must be space for 2K words in 
the background area and 2K words in the foreground area. The foreground job 
reserves 2K words of memory even if the complete task size is less than 2K 
words, and the background has a minimum size of 4K words for the USR and 
KMON. USR swapping is explained in Section 1.2.1.5. 

1.2.4.1 Calculating Workspace for a FORTRAN Foreground Program — Addi- 
tional workspace must be allocated in memory when running a FORTRAN 
program in the foreground of a foreground/background environment. For a 
foreground job, the space is allocated by the /BUFFERrn option of the FRUN 
command. (A background job uses whatever space is available between its 
high limit and the system's low limit.) When you allocate additional work- 
space in memory to run a FORTRAN program in the foreground, calculate the 
space required by using the following formula: 

n = [l/2[504+(33*N)+(R-136)+A*512)]] 

where: 

n = number of decimal words 

A = the maximum number of files open at any one time. If double 
buffering is used, A should be multiplied by 2 

N = the maximum number of simultaneously open channels (logical 
unit numuers); tue deiauit is 6 

R = maximum formatted record length; the default is 136 characters 

This formula must be modified for certain SYSLIB functions. 

The IQSET function requires the formula to include additional space for 
queue elements (qcount) as follows: 

n = [l/2[504+(33*N) + (R-136)+A*512]]+[10*qcount] 

The ICDFN function requires the formula to include additional space for the 
integer number of channels {num) as follows: 

n = [l/2(504+(33*N)+(R-136)-HA*512]]+(6*num] 

The INTSET function requires the formula to include additional space for the 
number of INTSET calls issued in the program as follows: 

n = [l/2[504+(33*N) + (R-136)+A*512]]+[25*INTSET] 

Any calls, including INTSET, that invoke completion routines must include 
64[decimal] words plus the number of words needed to allocate the second 
record buffer (default is 68[decimal] words). The length of the record buffer is 
controlled by the /RECORD option to the FORTRAN compiler. If the 
/RECORD option is not used, the allocation in the formula must be 136(deci- 
mal) bytes, or the length that was set at FORTRAN installation time. This 
modifies the formula as follows: 

n = [l/2[504+(33*N)+(R-136)+A*512]] + [64+R/2] 
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If the /BUFFER option does not allocate enough space in the foreground on 
the initial call to a completion routine, the following message appears: 

?ERR 0, NON-FORTRAN error call 

This message also appears if there is not enough free memory for the back- 
ground job or if a completion routine in the single-job monitor is activated 
during another completion routine. In the latter case, the job aborts; you 
should use the FB monitor to run multiple active completion routines. 

1.2.4.2 Running a FORTRAN Program in a Foreground/Bacl<ground 
Environment — This section briefly describes the procedure for running two 
FORTRAN programs, one in the background and one in the foreground. 

The background program named BACK is as follows: 



PROGRAM BACKGROUND 

IMPLICIT INTEGER(O) 

CALL I POKE ( "44 ,"10000. OR, I PEEK ( "44) ) 

CALL PRINTC 'HELLO FROM THE BACKGROUND' 

ICHAR=ITTINR( ) 

OCHAR=ITT0UR( ICHAR) 

GO TO 100 

END 



This program prints the message "HELLO FROM THE BACKGROUND" 
and will print the message each time you input a character at the terminal. 

The foreground program named FORE is as follows: 



PROGRAM FOREGROUND 
IMPLICIT INTEGER(O) 

CALL I POKE ( "44 ,"10000, OR. I PEEK ( "44) ) 
100 CALL PRINT( 'HELLO FROM THE FOREGROUND') 
ICHAR=ITTINR< ) 
OCHAR=ITTOUR( ICHAR) 
GO TO 100 
END 



After compiling both programs, link them. Link the foreground program using 
the LINK command with the /FOREGROUND option. This option produces 
a load module with a .REL file type that signifies to the system that the file is 
a foreground program and is to be run as a priority job. For example, 

.LINK/FOREGROUND FORE (H) 

Then you can assign the device that will be used for the output of the fore- 
ground program. You must also load into memory the peripheral device 
handlers needed by the foreground program. 

The command FRUN loads and starts execution of the foreground job. This 
command is similar to the RUN command except that the system automati- 
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cally loads and starts the execution of the foreground .REL program. If the 
command 

.FRUN FORE m 

is typed at this point, the error message 

'Err B2 FORTRAN start fail 

will be displayed. This message indicates that additional workspace allocation 
is required and that the /BUFFER option must be used. (Refer to the previous 
section for the formula to calculate the additional space needed.) Thus, the 
command would be typed as follows: 

.FRUN FORE/BUFFER: 760 M) 

Execution of this command results in the following output at the terminal: 

F > 

HELLO FROM THE FOREGROUND 



The system first identifies the message as foreground output. Then the fore- 
ground job executes and outputs its message. The background monitor next 
prints the characters B> and a period, indicating that control has returned to 
monitor command mode. Command input remains directed to the back- 
ground job. By typing 

.RUN BACK m 

the message from the background job will be displayed 

HELLO FROM THE BACKGROUND 

Each time a character is input to the terminal, say an "L", the message will 
be repeated. 

LHELLD FROM THE BACKGROUND 

Use the CTRL/F command to direct terminal input to the foreground job. The 
system prints F> to remind you that you are now directing input to the 
foreground job. When you type a character, say a "Y", the foreground job 
message will be displayed. 

F> 



Type a CTRL/B to return to the background job or a CTRL/C to return to 
monitor command mode. If you are returning to a background environment. 
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you should unload the foreground job and any handlers to reclaim memory 
space for background use. 

1.2.5 Linking witli FORLIB 

Normally, the default system library file (SYSLIB.OBJ) also includes the 
overlay handlers and the appropriate FORTRAN run-time system routines. 

To add FORLIB.OBJ modules to the default library SYSLIB.OBJ, use the 
following command: 

,LIBRARY/INSERT/REHOUE SYBLIB FDRLIB m 
Global? *OURH m 
Global? m 

1.2.6 SYSLIB Services Not Provided by Programmed Requests 

SYSLIB provides many services that are not provided by programmed 
requests. Such services are as follows: 

• Time conversion and date access 

• Program suspension 

• Two-word integer support (INTEGER*4) 

• Radix-50 conversion 

• Character string manipulation 

1.2.6.1 Time Conversion and Date Access — Several calls allow you to per- 
form time conversions and access the system date. 

You use the CVTTIM call to convert a two-word internal format time to 
hours, minutes, seconds, and ticks. The JTIME call converts a time given in 
hours, minutes, seconds, and ticks into the internal two-word time format. 

If you need to output the time on a printout, the TIMASC call converts the 
time returned by the .GTIM programmed request into an eight-character 
ASCII string; the TIME call returns the current time of day as an eight- 
character ASCII string. 

The current system date can be accessed by your program with a DATE call. 
The date is returned as a string value. IDATE performs similarly, but returns 
an integer value. 

1.2.6.2 Program Suspension — You suspend execution of a running program 
for a specified number of ticks with the ITWAIT call. You use the ISLEEP 
call to suspend a running program for a specified number of hours, minutes, 
seconds, and ticks. The lUNTIL call allows you to suspend job execution until 
a specific time of day, which is given to the routine in hours, minutes, sec- 
onds, and ticks. You can use this function to periodically collect data and to 
stop processing between acquisitions. 
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1.2.6.3 Two-Word Integer Support (INTEGER*4) — You can make calls to 
SYSLIB to manipulate a 32-bit integer that uses two words of storage. The 
first word contains the low-order part of the value and the second word con- 
tains the sign and the high-order part of the value. The range of numbers that 
is represented is -2(31) to 2(31)-1. This format differs from the two-word 
internal time format that stores the high-order part of the value in the first 
word and the low-order part in the second word. Table 1-8 shows the calls 
that you can use to convert from one format to another. 

Table 1-8: SYSLIB Conversion Calls 



From 


To 


Call 


INTEGER*2 (16-bit integer) 


INTEGER*4 


JICVT 


INTEGER*4 (32-bit integer) 


INTEGER*2 


IJCVT 


INTEGERS 


REAL*4 


AJFLT/IAJFLT 


INTEGERS 


REAL*8 


DJFLT/IDJFLT 


REAL*4 (2-word floating point) 


INTEGER*2 


JAFIX 


REAL*8 (4-word floating point) 


INTEGER*4 


JDFIX 



Calls are also available for you to perform arithmetic operations on 
INTEGER*4 values, move a value to a variable, and convert a two-word 
internal time format to and from an INTEGER*4 value. 

1.2.6.4 Radix-50 Conversion — You can convert ASCII characters to or from 
Radix-50. 

IRADoO converts a specified number of characters of Radix-50 and returns the 
number of characters converted as a function result. RAD50 encodes RT-11 
file descriptors in Radix-50 notation. R50ASC converts a specified number of 
Radix-50 characters to ASCII. 

1 .2.6.5 Character String Operations — o i oiJiB proviucs Cuaracter string 
functions that perform string operations such as concatenation, comparison, 
copying, replacing, and computing the number of characters in a string. For 
example, the following program will concatenate two character strings. 

.TITLE GETTOO 
.GLDBL CDNCAT 
.MCALL .PR I NT J, EX IT 



START: 


MOM «hRGBLK ,R5 




JSR PCtCONCAT 




.PRINT »STRCON 




.EXIT 


ARGBLK: 


.WORD 3 




.WORD BTRNGl 




.WORD STRNG2 




.WORD STRCON 


STRNG 1 : 


,ASCIZ /RESEARCH AND/ 


STRNG2: 


.ASCIZ / DEMELOPMENT/ 


STRCON: 


.BLKB 31 




• EMEN 




.END START 
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Running this program results in the concatenation of string 1 and string 2, and 
the output at the terminal is 

RESEARCH AND DEUELOPMENT 

The following section describes character string functions in detail. 

1.2.7 Character String Functions 

The SYSLIB character string functions and routines provide variable-length 
string support for RT-11 FORTRAN and for MACRO programs. SYSLIB 
calls perform the following character string operations: 

Call Operation 

GETSTR Reads character strings from a specified FORTRAN logical unit 

PUTSTR Writes character strings to a specified FORTRAN logical unit 

CONCAT Concatenates variable-length strings 

INDEX Returns the position of one string in another 

INSERT Inserts one string into another 

LEN Returns the length of a string 

REPEAT Repeats a character string 

SCOMP Compares two strings 

SCOPY Copies a character string 

STRPAD Pads a string with blanks on the right 

SUBSTR Copies a substring from a string 

TRANSL Performs character modification 

TRIM Removes trailing blanks 

VERIFY Verifies the presence of characters in a string 

Strings are stored in LOGICAL*! arrays that you define and dimension. 
These arrays store strings in ASCII format as one character per array element 
plus a zero element to indicate the current end of the string. 

The length of a string can vary at execution time from zero characters to one 
less than the size of the array that stores the string. The maximum size of any 
string is 32767 characters. Strings can contain any of the seven-bit ASCII 
characters except null{0), since the null character is used to mark the end of 
the string. The inclusion of a terminating zero byte constitutes an "ASCIZ" 
format, which is the format set up by a MACRO assembler directive .ASCIZ. 
This directive automatically sets up strings with a terminating zero byte. Bit 
7 of each character must be cleared. Therefore, the valid characters are those 
whose decimal representations range from 1 to 127, inclusive. 
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The ASCII code used in this string package is the same as that employed by 
FORTRAN for A-type FORMAT items, ENCODE/DECODE strings, and ob- 
ject-time format strings. Whenever quoted strings are used as arguments in 
the CALL statement, ASCIZ strings are generated for these routines by the 
FORTRAN compiler. Note that a null string (a string containing no charac- 
ters) can be represented in FORTRAN by a variable or constant of any type 
that contains the value zero, or by a LOGICAL variable or constant with the 
.FALSE, value. 

In many routines, it is difficult to predict the length of the string produced. To 
Pj-gygTi+ Q strin°" from overflowino' the arra^ that contains it, you can specify 
an optional integer argument to the subroutine. This argument, called len, 
limits the length of an output string to the value specified for len plus one (for 
the null terminator), so that the array receiving the result must be at least len 
plus one elements in size. 

NOTE 

If the string is larger than the array, other data may be de- 
stroyed and cause unpredictable results. 

When len is specified, you can also include the optional argument called err. 
Err is a logical variable that should be initialized by the FORTRAN program 
to the .FALSE, value. If a string function is given the arguments len and err, 
and len is actually used to limit the length of the string result, then err is set 
to the .TRUE, value. If len is not used to truncate the string, err is 
unchanged — that is, it retains a .FALSE, value. 

The argument len can appear alone. However, len must appear if err is speci- 
fied. The err argument should be used for GETSTR and PUTSTR. 

Several routines use the concept of character position. Each character in a 
string is assigned a position number. The first character in a string is in 
position one. Each subsequent character has a position number one greater 
than the character that precedes it. 

1.2.7.1 Allocating Character String Variables — A one-dimensional 
LOGICAL* 1 array can contain a single string whose length can vary from 
zero characters to one fewer than the dimensioned length of the array. For 
example, 

LOGICAL*! H(a5) iALLDCATE SPACE FOR STRING UARIABLE A 

allows array A to be used as a string variable that can contain a string of 44 or 
fewer characters. Similarly, a two-dimensional LOGICAL*! array can be used 
to contain a one-dimensional array of strings. Each string in the array can 
have a length up to one less than the first dimension of the LOGICAL*! array. 
There can be as many strings as the number specified for the second dimen- 
sion of the LOGICAL*! array. For example, 

LOGICAL*! W(21.10) ! ALLOCATE AN ARRAY OF STRINGS 

creates string array W that has ten string elements, each of which can contain 
up to 20 characters. String I in array W is referenced in subroutine or function 
calls as W(1,I). 
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The following example allocates a two-dimensional string array. 

LDGICAL#1 T(ia,5,7) ! ALLOCATE A 5 BY 7 STRING ARRAY 

Each string in array T may vary in length to a maximum of 13 characters. 
String I, J of the array can be referenced as T(1,I,J). Note that T is the same as 
T(l,l,l). This dimensioning process can create string arrays of up to six 
dimensions (represented by LOGICAL*! arrays of up to seven dimensions). 

1 .2.7.2 Passing Strings to Subprograms — There are three ways to pass strings 
to subprograms. 

1. LOGICAL*! arrays that contain strings can be placed in a COMMON 
block and referenced by any or all routines with a similar common decla- 
ration. However, when you place a LOGICAL*! array in a common block, 
make sure that the array is even in length or that the strings are together 
as the last elements in the COMMON block. Otherwise, all succeeding 
variables in the COMMON block may be assigned odd addresses. 

A LOGICAL*! array has an odd length only if the product of its dimen- 
sions is odd. For example, 

LOGICAL*! B(10,7) !(10*7) = 70! EUEN LENGTH 
LOGICAL*! H (21) !2! IS AN ODD LENGTH 

If odd-length arrays are to be placed in a COMMON block, either they 
should place them at the end of the block or pair them to result in an 
effective even length. For example, 

COMMON A! ,A2,A3(10) »H(21 ) ! PLACE ODD-SIZED ARRAY AT END 

or 

COMMON Al ,A2 ,H(21 ) .HI (7) ,A3( 10) !PAIR DDD-BIZE ARRAYS H AND HI 

These restrictions apply only to LOGICAL*! variables and arrays. 

2. A single string can be passed by using its array name as an argument. For 
example, 

LOGICAL*! A(21) ISTRING VARIABLE A, 20 CHARACTERS MAXIMUM 
CALL SUBR(A) 

passes string A to subroutine SUBR. 

3. If the calling program has declared a multi-dimensional array, and only 
one string of that array is to be passed to a subroutine, then the subroutine 
call should specify the first element of the string to be passed (this re- 
quires that the first dimension of the array equals the maximum length of 
each string). 

For example, 

LOGICAL*! NAMES (81.20) ! 20 NAMES. 80 CHARACTERS EACH 
LOGICAL*! ERR 



DO !0 NAMNUM=1.20 ! GET ALL 20 NAMES 
10 CALL GETSTR ( 5 .NAMES ( 1 .NAMNUM ) ,80 .ERR ) ! FROM TT 
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If the maximum length of a string argument is unknown in a subroutine or 
function, or if the routine is used to handle many different lengths, the 
dummy argument in the routine should be declared as a LOGICAL*! array 
with a dimension of one, such as LOGICAL*! ARG(!). In this case, the string 
routines correctly determine the length of ARG whenever it is used, but it is 
not possible to determine the maximum size of any string that can be stored 
in ARG. If a multidimensional array of strings is passed to a routine, it must 
be declared in the called program with the same dimensions that were speci- 
fied in the calling program. 






The length argument specified in many of the character string 
functions refers to the maximum length of the string excluding 
the necessary null byte terminator. The length of the 
LOGICAL*! array to receive the string must be at least one 
greater than the length argument. 

1.2.7.3 Using Quoted-String Literals — You can use quoted strings as argu- 
ments to any of the string routines that are invoked as functions or with the 
CALL statement. For example, 

CALL SCDMP(h4AME t 'SMYTHE . R'tM) 

compares the string in the array NAME to the constant string SMYTHE, R 
and sets the value of the integer variable accordingly. 

1.2.8 System Subroutine Summary 

Table !-9 lists the SYSLIB subroutines alphabetically within categories, the 
sections in which they are located, and a brief description of each subroutine. 
Those subroutines prefaced with an asterisk (*) are allowed only in a 
foreground/background environment, under either the FB or XM monitor. 
The SYSLIB subroutines do not support the XM monitor mapping pro- 
grammed requests. Use FORTRAN virtual arrays to access extended memory. 

Table 1-9: Summary of SYSLIB Subroutines 



Name 



Section 



Description 



File-Oriented Operations 



CLOSEC, 
ICLOSE 


3.3 


IDELET 


3.21 


lENTER 


3.24 


IRENAM 


3.43 


LOOKUP 


3.74 



Closes the specified channel. 

Deletes a file from the specified device. 

Creates a new file for output. 

Changes the name of the indicated file. 

Opens an existing file for input and/or output via the specified 
channel. 



(continued on next page) 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



Data Transfer Operations 

GTLIN 



*IRCVD 
*IRCVDC 
*IRCVDF 
*IRCVDW 

IREAD 



IREADC 



IREADF 



IREADW 

*ISDAT 
*ISDATC 
*ISDATF 
*ISDATW 

ITTINR 

ITTOUR 

IWAIT 

IWRITC 



IWRITE 



IWRITF 



IWRITW 



3.11 



3.41 



3.42 



3.42 



3.42 



3.42 
3.48 



3.54 
3.55 
3.59 

3.60 



3.60 



3.60 



3.60 



Transfers a line of input from the console terminal or indirect 
file (if active) to the user program. 

Receives data. Allows a job to read messages or data sent by 
another job in an FB environment. The four modes correspond 
to the IREAD, IREADC, IREADF, and IREADW modes. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in the 
I/O queue. No special action is taken upon completion of I/O. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in the 
I/O queue. Upon completion of the read, control transfers to 
the assembly language routine specified in the IREADC func- 
tion call. 

Transfers data from a file to a memory buffer and returns 
control to the user program when the request is entered in the 
I/O queue. Upon completion of the read, control transfers to 
the FORTRAN subroutine specified in the IREADF function 
call. 

Transfers data from a file to a memory buffer and returns 
control to the program only after the transfer is complete. 

Allows the user to send messages or data to the other job in an 
FB environment. The four functions correspond to the 
IWRITE, IWRITC, IWRITF, and IWRITW modes. 

Gets one character from the console keyboard. 

Transfers one character to the console terminal. 

Waits for completion of all I/O on a specified channel (com- 
monly used with the IREAD and IWRITE functions). 

Transfers data to a file and returns control to the user program 
when the request is entered in the I/O queue. Upon completion 
of the write, control transfers to the assembly language routine 
specified in the IWRITC function call. 

Transfers data to a file and returns control to the user program 
when the request is entered in the I/O queue. No special action 
is taken upon completion of the I/O. 

Transfers data to a file and returns control to the user program 
when the request is entered in the I/O queue. Upon completion 
of the write, control transfers to the FORTRAN subroutine 
specified in the IWRITF function call. 

Transfers data to a file and returns control to the user program 
only after the transfer is complete. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



Data Transfer Operations (cont.) 



MTATCH 

MTDTCH 

MTGET 

MTIN 

MTOUT 

MTPRNT 

MTRCTO 

MTSET 

MTSTAT 
*MWAIT 
PRINT 



3.76 

3.77 

3.78 

3.79 

3.80 

3.81 

3.82 

3.83 

3.84 
3.85 
3.86 



Attaches a particular terminal in a multi-terminal environ- 
ment 

Detaches a particular terminal in a multi-terminal environ- 
ment 

Provides information about a particular terminal in a multi- 
terminal system. 

Transfers characters from a specific terminal to the user pro- 
gram in a multi-terminal system. 

Transfers characters to a specific terminal in a multi-terminal 
system. 

Prints a message to a specific terminal in a multi-terminal 
system. 

Enables output to terminal by canceling the effect of a previ- 
ously typed CTRL/0. 

Sets terminal and line characteristics in a multi-terminal sys- 
tem. 

Returns multi-terminal system status. 

Waits for messages to be processed. 

Outputs an ASCII string to the console terminal. 



Channel-Oriented Operations 



ICDFN 
*ICHCPY 

*ICSTAT 
IFREEC 

IGETC 

ILUN 

IREOPN 

ISAVES 

PURGE 



3.15 
3.16 

3.20 

3.26 

3.27 
3.31 

3.44 
3.45 
3.87 



Defines additional I/O channels. 

Allows access to files currently open in the other job's environ- 
ment. 

Returns the status of a specified channel. 

Returns the specified RT-11 channel to the available pool of 
channels for the FORTRAN I/O system. 

Allocates an RT-11 channel and informs the FORTRAN I/O 
system of its use. 

Returns the RT-11 channel number with which a FORTRAN 
logical unit is associated. 

Restores the parameters stored via an ISAVES function and 
reopens the channel for I/O. 

Stores five words of channel status information into a user- 
specified array and deactivates the channel. 

Deactivates a channel. 



Device and File Specifications 



lASIGN 
ICSI 



3.14 
3.19 



Sets information in the FORTRAN logical unit table. 

Calls the RT-11 CSI in special mode to decode file specifica- 
tions and options. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 


Section 


Description 


1 1 

Timer Support Operations 


CVTTIM 


3.5 


Converts a two-word internal format time to hours, minutes, 
seconds, and ticks. 


GTIM 


3.9 


Gets time of day. 


ICMKT 


3.18 


Cancels an unexpired ISCHED, ITIMER, or MRKT request 
(valid under FB and XM, and for SJ monitors with timer 
support, a SYSGEN option). 


ISCHED 


3.46 


Schedules the specified FORTRAN subroutine to be entered 
at the specified time of day as an asynchronous completion 
routine (valid under FB and XM, and for SJ monitors with 
timer support, a special feature). 


*ISLEEP 


3.49 


Suspends main program execution of the running job for a 
specified amount of time; completion routines continue to run. 


ITIMER 


3.52 


Schedules the specified FORTRAN subroutine to be entered 
as an asynchronous completion routine when the time interval 
specified has elapsed (valid under FB and XM, and for SJ 
monitors with timer support, a special feature). 


*ITWAIT 


3.56 


Suspends the running job for a specified amount of time; com- 
pletion routines continue to run. 


nUNTIL 


3.57 


Suspends the main program execution of the running job until 
a specified time of day; completion routines continue to run. 


JTIME 


3.71 


Converts hours, minutes, seconds, and ticks into two-word in- 
ternal format time. 


MRKT 


3.75 


Schedules an assembly language routine to be activated as an 
asynchronous completion routine after a specified interval 
(valid under FB and XM, and for SJ monitors with timer 
support, a special feature). 


SECNDS 


3.98 


Returns the current system time in seconds past midnight 
minus the value of a specified argument. 


TIMASC 


3.103 


Converts a specified two-word internal format time into an 
eight-character ASCII string. 


TIME 


3.104 


Returns the current system time of day as an eight-character 
ASCII string. 


RT-11 Services 






CHAIN 


3.2 


Chains to another program (from the background job only). 


*DEVICE 


3.6 


Specifies actions to be taken on normal or abnormal program 
termination, such as turning off interrupt enable on user-pro- 
grammed devices. 


GTJBJGTJB 


3.10 


Returns the parameters of the specified job. 


IDSTAT 


3.23 


Returns the status of the specified device. 


IFETCH 


3.25 


Loads a device handler into memory. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



RT-11 Services (cont.) 



IQSET 

ISPFN 
ISPFCN 

TCt>T7TS.TTr 

ISPFNW 
*ITLOCK 

LOCK 



RCHAIN 
RCTRLO 

♦RESUME 

SCCA 

SETCMD 

*SUSPND 

UNLOCK 



3.39 
3.50 

3.53 
3.73 

3.91 
3.92 

3.94 

3.95 

3.99 

3.102 

3.107 



Description 



Expands the size of the RT-11 monitor queue from the free 
space managed by the FORTRAN system. 

Issues special function requests to various handlers, such as 
magtape. The four modes correspond to the IWRITE, 
TWRTTP TWRTTF and IWRITW modes. 



Indicates whether the USR is currently in use by another job 
and performs a LOCK if the USR is available. 

Makes the RT-11 monitor User Service Routine (USR) perma- 
nently resident until an UNLOCK function is executed. If 
necessary, a portion of the user's program is swapped out to 
make room for the USR. 

Allows a program to access variables passed across a chain. 

Enables output to the terminal by canceling the effect of a 
previously typed CTRL/O. 

Causes the main program execution of a job to resume at the 
point it was suspended by a SUSPND function call. 

Intercepts a CTRL/C command initiated at the console termi- 
nal. 

Passes command lines to the keyboard monitor for execution 
after the program exits. 

Suspends main program execution of the running job; comple- 
tion routines continue to execute. 

Releases the USR if a LOCK was performed; the user program 
is swapped in if required. 



INTEGER*4 Support Functions 

AJFLT 



DJFLT 

lAJFLT 

IDJFLT 

IJCVT 
JADD 
JAFIX 

.irMP 



3.1 

3.7 

3.13 

3.22 

3.30 
3.61 
3.62 
.3 63 



Converts a specified INTEGER*4 value to REAL*4 and re- 
turns the result as the function value. 

Converts a specified INTEGER*4 value to REAL*8 and re- 
turns the result as the function value. 

Converts a specified INTEGER*4 value to REAL*4 and stores 
the result. 

Converts a specified INTEGER*4 value to REAL*8 and stores 
the result. 

Converts a specified INTEGER*4 value to INTEGER*2. 

Computes the sum of two INTEGER*4 values. 

Converts a REAL*4 value to INTEGER*4. 

Compares two INTEGER*4 values and returns an 
INTEGER*2 value that reflects the signed comparison result. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 



Section 



Description 



INTEGER*4 Support Functions (cont.) 



JDFIX 


3.64 


JDIV 


3.65 


JICVT 


3.66 


JJCVT 


3.67 


JMOV 


3.68 


JMUL 


3.69 


JSUB 


3.70 



Converts a REAL*8 value to INTEGER*4. 

Computes the quotient and remainder of two 
INTEGERS values. 

Converts an INTEGER*2 value to INTEGERS. 

Converts the two-word internal time format to 
INTEGER*4 format, and vice versa. 

Assigns an INTEGER*4 value to a variable. 

Computes the product of two INTEGER*4 values. 

Computes the difference between two INTEGER*4 
values. 



Character String Functions 



CONCAT 
GETSTR 

INDEX 



3.4 
3.8 

3.32 



INSERT 


3.33 


ISCOMP 


3.47 


IVERIF 


3.58 


LEN 


3.72 


PUTSTR 


3.84 


REPEAT 


3.93 


SCOMP 


3.96 


SCOPY 


3.97 


STRPAD 


3.100 


SUBSTR 


3.101 


TRANSL 


3.105 


TRIM 


3.104 


VERIFY 


3.106 



Concatenates two variable-length strings. 

Reads a character string from a specified FORTRAN logical 
unit. 

Returns the location in one string of the first occurrence of 
another string 

Replaces a portion of one string with another string. 

Compares two character strings. 

Indicates whether characters in one string appear in another. 

Returns the number of characters in a specified string. 

Writes a variable -length character string on a specified FOR- 
TRAN logical unit. 

Concatenates a specified string with itself to provide an indi- 
cated number of copies and stores the resultant string. 

Compares two character strings. 

Copies a character string from one array to another. 

Pads a variable-length string on the right with blanks to create 
a new string of a specified length. 

Copies a substring from a specified string. 

Replaces one string with another after performing character 
modification. 

Removes trailing blanks from a character string. 

Indicates whether characters in one string appear in another. 



FB and XM monitors only. 
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Table 1-9: Summary of SYSLIB Subroutines (Cont.) 



Name 


Section 


Description 


1 
Radix-50 Conversion Operations 


IRAD50 


3.40 


Converts characters in ASCII format to Radix-50, 
returning the number of characters converted. 


R50ASC ■ 


3.89 


Converts characters in Radix-50 format to ASCII. 


RAD50 


3.90 


Converts six ASCII characters, returning a REAL*4 
result that is rhe two-word Radix-50 value. 


Miscellaneous Services 




lADDR 


3.12 


Obtains the memory address of a specified entity. 


IGETSP 


3.28 


Returns the address and size (in words) of free space obtained 
from the FORTRAN system. 


INTSET 


3.34 


Establishes a specified FORTRAN subroutine as an interrupt 
service routine with a specified priority. 


IPEEK 


3.35 


Returns the value of a word located at a specified absolute 
memory address. 


IPEEKB 


3.36 


Returns the value of a byte located at a specified byte address. 


IPOKE 


3.37 


Stores an integer value in an absolute memory location. 


IPOKEB 


3.38 


Stores an integer value in a specified byte location. 


ISPY 


3.51 


Returns the integer value of the word located at a specified 
offset from the beginning of the RT-U resident monitor. 



FB and XM monitors only. 
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Chapter 2 

Programmed Request Description and Examples 



This chapter presents the programmed requests alphabetically, describing 
each one in detail and providing an example of its use in a program. Also 
described are macros and subroutines that are used to implement device 
handlers and interrupt service routines. The following parameters are com- 
monly used as arguments in the various calls: 

addr an address, the meaning of which depends on the request 

being used. 

area a pointer to the EMT argument block for those requests that 

require a block. 

blk a block number specifying the relative block in a file or de- 

vice where an I/O transfer is to begin. 

buf a buffer address specifying a memory location into which or 

from which an I/O transfer will be performed; this address 
has to be word-aligned — that is, located at an even address 
and not a byte or odd address. 

cblk the address of the five-word block where channel status infor- 

mation is stored. 

chan a channel number in the range 0-377(octal). 

chrcnt a character count in the range l-255(decimal). 

code a flag used to indicate whether the code is to ue set m an 

EMT 375 programmed request. 

crtn the entry point of a completion routine. 

dblk a four-word Radix-oO descriptor block that specifies the phy- 

sical device, file name, and file type to be operated upon (see 
Section 1.1.2.6). 

func a numerical code indicating the function to be performed. 

jobblk a pointer to a three-word ASCII system job name. 

jobdev a pointer to a four-word system-job descriptor where the first 
word is a Radix-50 device name and the next three words 

/^/-iT^+ain Qi-i AQPTT c\;atpm.inh nntnp (fnr kpvwnrd armiment 

use, refer to this as a "dblk")- 
num a number, the value of which depends on the request. 
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seqnum a file number. 

For cassette operation, a value of is assumed if this argu- 
ment is blank. 

For magtape operation, this argument describes a file se- 
quence number. The values that the argument can have are 
described under the applicable programmed requests. 

unit the logical unit number of a particular terminal in a multi- 

terminal system. 

went a word count specifying the number of words to be trans- 

. ferred to or from the buffer during an I/O operation. 

Many programmed requests are qualified as special features. These requests 
are enabled only if you performed a system generation process, that is, they 
are not available in a distributed monitor. 



2.1 .CDFN 



The .CDFN request redefines the number of I/O channels. Each job, whether 
foreground or background, is initially provided with 16(decimal) I/O channels 
numbered 0-15. .CDFN allows the number to be expanded to as many as 256 
(decimal) channels (0-255). 

The space for the new channels is taken from within the user program. Each 
I/O channel requires five words of memory. Therefore, you must allocate 5*n 
words of memory, where n is the number of channels to be defined. 

It is recommended that you use the .CDFN request at the beginning of a 
program before any I/O operations have been initiated. If more than one 
.CDFN request is used, the channel areas must either start at the same 
location or not overlap at all. The two requests .SRESET and .HRESET 
cause the channels to revert to the original 16 channels defined at program 
initiation. Hence, you reissue any .CDFNs after using .SRESET or 
.HRESET. The keyboard monitor command CLOSE does not work if your 
program defines new input or output channels with the .CDFN request. 

The .CDFN request defines new channels so that the space for the previously 
defined channels cannot be used. Thus, a .CDFN for 20(decimal) channels 
(while 16 original channels are defined) creates 20 new I/O channels; the space 
for the original 16 is unused, but the contents of the old channel set are copied 
to the new channel set. 

If a program is overlaid, the overlay handler uses channel 15 (decimal) and 
this channel should not be modified. (Other channels can be defined and used 
as usual.) 

If an XM monitor environment, the area supplied for additional channels 
specified by the .CDFN request must lie in the lower 28K words of memory. In 
addition, it must not be in the virtual address space mapped by Kernel PARI, 
specifically the area from 20000 to 37776(octal). If you supply an invalid area, 
the system generates an error message. 
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Macro Call: .CDFN area,addr,num 

where: 

area is the address of a three-word EMT argument block 
addr is the address where the I/O channels begin 
num is the number of I/O channels to be created 

Request Format: 



itu 



area: 



addr 



num 



Errors: 



Code 



Explanation 



An attempt was made to define fewer channels than already 
exist. In an XM environment, an attempt to violate the PARI 
restriction sets the carry bit and returns error code in byte 52. 



Example: 



.TITLE CDFN. MAC 

J + 

i .CDFN - This is sn enample in the use of the .CDFN renuest. The 
; evtanple defines 32 new channels to reside in the body of the 
> pro^rsm. 



.MCALL 



■CDFN. .PRINT. .EXIT 



START? 


.CDFN 


»AREA.*CHANL.*32. 




ECC 


1* 




.PRINT 


♦BADCD 




.EXIT 




1*: 


.PRINT 
.EXIT 


♦GOODCD 


area: 


• ELKU 


3 


chanl: 


.6LKU 


5*32. 


BADCD! 


.ASCIZ 


/? .CDFN Failed ?/ 


GOODCD! 


.ASCIZ 


/.CDFN Successful/ 



.Use .CDFN to define 32. new channels 

.Branch if successful 

jprint failure message on console 

.Exit program 

JPrint success roessaae 

.Then exit 

lEMT Argument Block 
fSpace for new channels 

.Failure message 
(Success message 



• END 



START 



2.2 .CHAIN 



The .CHAIN request allows a background program to pass control directly to 
another background program without operator intervention. Since this pro- 
cess can be repeated, a long "chain" of programs can be strung together. 

The area in low memory from locations 500-507 contains the device name and 
file name (in Radix-50) to be chained to. The area from locations 510-777 is 
used to pass information between the chained programs. 
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Macro Call: .CHAIN 
Request Format: 



RO = 10 



Notes: 

1. Make no assumptions about which areas of memory remain intact across a 
.CHAIN. In general, only the resident monitor and locations 500-777 are 
preserved across a .CHAIN. In a .CHAIN from a virtual job, locations 
500-777 are not preserved. 

2. I/O channels are left open across a .CHAIN for use by the new program. 
However, new I/O channels opened with a .CDFN request are not avail- 
able in this way. Since the monitor reverts to the original 16 channels 
during a .CHAIN, programs that leave files open across a .CHAIN should 
not use .CDFN. Furthermore, nonresident device handlers are released 
during a .CHAIN request and must be fetched again by the new program. 
Note that FORTRAN logical units do not stay open across a .CHAIN. 

3. An executing program determines whether it was chained to or RUN from 
the keyboard by examining bit 8 of the Job Status Word. The monitor sets 
this bit if the program was invoked with .CHAIN request. If the program 
was invoked with R or RUN command, this bit remains cleared. If bit 8 is 
set, the information in locations 500-777 is preserved from the program 
that issued the .CHAIN and is available for the currently executing pro- 
gram to use. Again, locations 500-777 are not preserved in a .CHAIN from 
a virtual job. 

An example of a calling and a called program is MACRO and CREF. 
MACRO places important information in the chain area, locations 
500-777, then chains to CREF. CREF tests bit 8 of the JSW. If it is clear, 
it means that CREF was invoked with the R or RUN command and the 
chain area does not contain useful information. CREF aborts itself imme- 
diately. If bit 8 is set, it means that CREF was invoked with .CHAIN and 
the chain area contains information placed there by MACRO In this case, 
CREF executes properly. 



Errors: 



9_/i 



.CHAIN is implemented by simulating the monitor RUN command and 
can produce any errors that RUN can produce. If an error occurs, the 
.CHAIN is abandoned and the keyboard monitor is entered. Since vir- 
tual jobs must be run with the R command, a .CHAIN to a virtual job is 
illegal. 

When using .CHAIN, be careful with initial stack placement. The 
linker normally defaults the initial stack to lOOO(octal); if caution is not 
observed, the stack can destroy chain data before it can be used. 
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Example: 



.TITLE CHAIN. MAC 

.CHAIN - This example demonstrates the use of the .CHAIN 
proSram reauest. It chsins to program 'CTEST.SAV' and passes it 
3 command line taped in at the console terminal. As an exercise 
write the proaram 'CTEST' - in it» check, to see if it was chained 
to» and if so> echo the data passed to itj otherwise print the 
message 'Has not chained to". 



.MCALL 



.CHAIN- .TTYINi .PRINT 



START! 



loop: 



CHPTR! 



promt: 



Moy 


*500rR] 




nOv 


tCHPTR 


R2 


.rept 


4 




Moy 


(R2)+r 


Rl) + 


.ENDR 






.PRINT 


♦PROMT 




.TTYIN 






HOyB 


R0»(R1)+ 


CHPE 


R0,*12 




BNE 


LOOP 




CLRB 


@R1 




.CHAIN 






.RAD50 


/DK/ 




.RADSO 


/CTEST 


/ 


.RAD50 


/sAy/ 




.ASCII 


/Enter 


date to 


.END 


START 





fRl => Chain area 

iMove the Program Fllespec 

(into the Chain area... 

f 

fAsk for the data to be passed 

fNow Set a 'command' line 

fto pass to the chained program 

fin locations 510 and up. 

iLoop until line feed. 

?Put in a null byte as a terminator. 

fChain to the ne>;t program. 

fRADSO File spec. . . 



be passed to CTEST 



/<200> 



f% IN CASE YOU DON'T HAVE TIME HERE'S AN EXAMPLE * 
!* 'CTEST. MAC PROGRAM... * 

.TITLE CTEST. MAC 





.MCALL 


.PRINT, .EXIT 




JSU = 44 




CHAIN$ 


= 400 


CTEST! 


BIT 


♦CHAIN*, e*jsu 




BEQ 


1* 




.PRINT 


♦ CHAINIi 




Moy 


♦510»R0 




.PRINT 






• EXIT 




1*! 


.PRINT 
.EXIT 


♦NOCHN 


chaind: 


.ASCIZ 


/CTEST was ch 


NOCHN J 


.ASCIZ 


/CTEST was no 




.END 


CTEST 



fLocation of JSW 
fCHAIN bit in JSU 

fUere we chained to? 
jBranch if not 
iSau we were. . . 
JGet addr of start of data 
iPrint it out 
fE;;it program 

iSay we weren't chained to 
fThen exit 
led to - and here's the data passed.../ 



2.3 .CHCOPY (FB, XM, and System Jobs Only) 

The .CHCOPY request opens a channel for input, logically connecting it to a 
file that is currently open by another job for either input or output. This 
request can be used by either a foreground, background, or system job and 
must be issued before the first .READ or .WRITE request. 















However, no errors are detected by the system if another device is used. (To 
close a channel following use of .CHCOPY, use either the .CLOSE or .PURGE 
request.) 
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Macro Call: .CHCOPY area,chan,ochan [jobblk] 
where: 

area is the address of a three-word EMT argument block 

chan is the channel the current job will use to read the data 

ochan is the channel number of the other job's channel to be copied 

jobblk is a pointer to a three-word ASCII logical job name that repre- 
sents a system job (see the RT-11 System User's Guide) 

Request Format: 

RO ->• area: 



13 



chan 



ochan 



jobblk 



Notes: 

1. If the other job's channel was opened with .ENTER in order to create a 
file, the copier's channel indicates a file that extends to the highest block 
that the creator of the file had written at the time the .CHCOPY was 
executed. 

2. A channel open on a non-file-structured device should not be copied, 
because intermixture of buffer requests can result. 

3. A program can write to a file (that is being created by the other job) on a 
copied channel just as it could if it were the creator. When the copier's 
channel is closed, however, no directory update takes place. 

4. Foreground and background jobs may optionally leave the jobblk argu- 
ment blank or set it to zero. This causes the job name to default to F if the 
background job issued the request, or to B if the foreground job issued the 
request. 



Errors: 



Code 



1 



Explanation 

Other job does not exist, does not have enough channels de- 
fined, or does not have the specified channel (ochan) open. 

Channel (chan) already open. 



Example: 



.CHCOPY - This is an e)-;3«iple in the use of the .CHCOPY reouest. 
The exsmple consists of two proaraitSf 3 Foresround Job which 
creates a file and sends 3 message to a BackSround prosram 
which copies the FG channel and reads 3 record from the file. 
Both prosrams must be assembled and linked separately. 

.TITLE CHCOPF.MAC 

5 This is the Foreground prosiram ... 
r ~ 

.MCALL . ENTER r .PRINT > .SBATU. .EXIT r . RCVDU . . CLOSEt . WRITW 



H- 
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STARTFt 


Moy 


♦AREA>R5 




.ENTER 


R5r*0i*FILE.*5 




.URITU 


R5»*0t*RECRD,*256 




BCS 


ENTERR 




.SDATW 


R5!*BUFR.*2 




f 

.RCUDU 


RS>*BUFR>tl 




.CLOSE 


#0 




.PRINT 


♦FEXIT 




.EXIT 




enterr: 


.PRINT 
.EXIT 


♦ERHSG 


file; 


.RAD50 


/UK QUFILE/ 




.RADSO 


/TMP/ 


area: 


.ELKU 


5 


bUFS t 


. WORB 







.UORD 


4 


recrd: 


.BLKU 


256. 


ermsg: 


. ASCIZ 


/TEnter Error?/ 


fexit: 


.ASCIZ 


/FG Job GKitinS/ 




.END 


STARTF 



f*4 



;R5 => EMT arauBent block 

iCreate a 5 block file 

iUrite a record BG is interested in 

iBranch on error 

(Send messasle with info to EG 

rliD some other processing 

iUhen it's tine to exitmake sure 

fBG is done with the file 

JTell user we're Soing bae-bae 

SExit the proaram 

JPrint error message 

fthen exit 

(File spec for .ENTER 

JEMT arauBent block 



f Block * 
fFile record 
lError messaae text 
•Exit nesssae 



•TITLE CHCOPB.MAC 

r This is the Backaround proaram ... 
y - 

.MCALL .CHCOPYr .RCMDW. .READU . . EXITi .PRINT. .SDATU 



} + 



3TARTB! 


nOV 


#ARtA.R5 






}R5 => EMT ars block 




.RCVDU 


R5»*MSG.*2 






iUait for messaae from FG 




ECS 


1* 






.Branch if no FG 




.CHCOPY 


R5.*0,HSG+2 






.Channel ♦ is 1st word of messaae 




BCS 


2* 






{Branch if FG channel not open 




.READU 


R5.*0,*EUFF,*256 


. .MSG+4 


.Read block which is 2nd word of ms 




BCS 


3t 






iBranch if read error 




f 


. 






.Continue processina. . . 




.SDATW 


R5,»MS6,»1 






.Tell FG we're thru with file 




.PRINT 


♦BEXIT 






jTell user we're thru 




.EXIT 








jthen exit proaram 


1*; 


MOV 


♦NOJOB. RO 






jRO => No FG error msa 




BR 


At 






.Branch to print nisa 


2$: 


Moy 


♦NOCH.RO 






»R0 => FG ch not open nisa 




BR 


4$ 






.Branch. . . 


3$: 


MOV 


♦RDERR. RO 






jRO => Read err msa 


4*; 


.PRINT 
.EXIT 








(Print proper error msa 
.then exit. 


area: 


.BLKU 


5 






.■EMT araument blk 


msg; 


.BLKU 


3 






JMessaae buffer 


buff; 


.BLKU 


256. 






.File buffer 


bexit: 


.ASCIZ 


/Channel -Record 


ropy 


successful/ 


nojob; 


.ASCIZ 


/?No FG Job?/ 






.Error messages... 


noch: 


.ASCIZ 


/?FB channel not 


open 


-?/ 




rderr: 


.ASCIZ 
.END 


/?Resd Error?/ 
STARTB 









2.4 .CLOSE 



The .CLOSE request terminates activity on the specified channel and frees it 
for use in another operation. The handler for the associated device must be in 
memory if the file was created with a .ENTER programmed request. 

Macro Call: .CLOSE chan 



Request Format: 
RO = 



6 



chan 



A .CLOSE request specifying a channel that is not open is ignored. 
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A file opened with .LOOKUP does not require any directory operations when 
a .CLOSE is issued, and the USR does not have to be in memory for such a 
.CLOSE. The USR is required if, while the channel is open, a request was 
issued that required directory operations. The USR is always required for 
special structured devices such as magtape. 

A .CLOSE is required on any channel opened with .ENTER if the associated 
file is to become permanent. 

NOTE 

Do not close channel 17 (octal) if your program is overlaid, 
because overlays are read on that channel. 

A .CLOSE performed on a file opened with .ENTER causes the device direc- 
tory to be updated to make that file permanent. The first file in the directory 
with the same name, if one exists, is deleted, provided that it is not protected. 
When a file that is opened with an .ENTER request is closed, its permanent 
length reflects the highest block written since it was entered. For example, if 
the highest block written is block number 0, the file is given a length of 1; if 
the file was never written, it is given a length of 0. If this length is less than 
the size of the area allocated at .ENTER time, the unused blocks are re- 
claimed as an empty area on the device. 

In magtape operations, the .CLOSE request causes the handler to write an 
ANSI EOFl label in software mode (using MM. SYS, MT.SYS, or MS.SYS) 
and to close the channel in hardware mode (using MMHD.SYS, MTHD.SYS, 
or MSHD.SYS). 

Errors: 

Code Explanation 

3 A protected file with the same name already exists on the de- 
vice. The .CLOSE is performed anyway, resulting in two files 
with the same name on the device. 

.CLOSE does not return any other errors unless the .SERR request has 
been issued. If the device handler for the operation is not in memory, 
and the .CLOSE request requires updating of the device directory, a 
fatal monitor error is generated. 

Example: 

Refer to the examples for the .CSISPC and .WRITW requests, which 
show typical uses for .CLOSE. 



2.5 .CMKT (FB and XM. SJ Monitor Special Feature) 

The .CMKT request causes one or more outstanding mark time requests to be 
canceled (see the .MRKT programmed request). The .CMKT request is a 
special feature in the SJ monitor, and is selected with the timer support 
during the system generation process. 
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Macro Call: .CMKT area,id[,time] 

where: 

area is the address of a three-word EMT argument block 

id is a number that identifies the mark time request to be can- 

celed. If more than one mark time request has the same id, the 
request with the earliest expiration time is canceled. If id = 0, 
all non-system mark time requests (those in the range 1-177377) 
for the issuing job are canceled 

time is the address of a two-word area in which the monitor returns 
the amount of time (clock ticks) remaining in the canceled re- 
quest. The first word contains the high-order time, the second 
contains the low-order. If an address of is specified, no value is 
returned. If id = 0, the time parameter is ignored and need not 
be indicated 

Request Format: 

RO -► area: 



23 



id 



time 



Notes: 

1. Canceling a mark time request frees the associated queue element. 

2. A mark time request can be converted into a timed wait by issuing a 
.CMKT followed by a .TWAIT, and by specifying the same time area. 

3. If the mark time request to be canceled has already expired and is waiting 
in the job's completion queue, .CMKT returns an error code of 0. It does 
not remove the expired request from the completion queue. The comple- 

Liun ruuLiiie will cvciituaiij' ud imi. 

Errors: 

Code Explanation 

The id was not zero and a mark time request with the specified 
identification number could not be found (implying that the 
request was never issued or that it has already expired). 

Example: 

Refer to the example for the .MRKT request. 



2.6 .CNTXSVV (FB and XM Only) 

A context switch is an operation performed when a transition is made from 
running one job to running another. The .CNTXSW request is used to specify 
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locations to be included in a list when jobs are switched between background 
and foreground. Refer to the RT-11 Software Support Manual for further 
details. 

The system always saves the parameters it needs to uniquely identify and 
execute a job. These parameters include all registers and the following loca- 
tions: 

34,36 Vector for TRAP instruction 
40-52 System Communication Area 

If an .SFPA request has been executed with a non-zero address, all floating- 
point registers and the floating-point status are also saved. 

It is possible that both jobs want to share the use of a particular location not 
included in normal context-switch operations. For example, if a program uses 
the lOT instruction to perform an internal user function (such as printing 
error messages), the program must set up the vector at 20 and 22 to point to 
an internal lOT trap handling routine. If both foreground and background 
wish to use lOT, the lOT vector must always^point to the proper location for 
the job that is executing. Including locations 20 and 22 in the .CNTXSW list 
for both jobs before loading these locations accomplishes this. This procedure 
is not necessary for jobs running under the XM monitor. In the XM monitor, 
both lOT and BPT vectors are automatically context-switched. 

If .CNTXSW is issued more than once, only the latest list is used; the previ- 
ous address list is discarded. Thus, all addresses to be switched must be 
included in one list. If the address (addr) is 0, no extra locations are switched. 
The Hst cannot be in an area into which the USR swaps, nor can it be 
modified while a job is running. 

In the XM monitor, the .CNTXSW request is ignored for virtual jobs, since 
they do not share memory with other jobs. For virtual jobs, the lOT, BPT, 
and TRAP vectors are simulated by the monitor. The virtual job sets up the 
vector in its own virtual space by any of the usual methods (such as a direct 
move or an .ASECT). When the monitor receives a synchronous trap from a 
virtual job that was caused by an lOT, BPT, or TRAP instruction, it checks 
for a valid trap vector and dispatches the trap to the user program in user 
mapping mode. An invalid trap vector address will abort the job with the 
following fatal error message: 

7M0N-F-I11 sst (illegal synchronous system trap) 
Macro Call: .CNTXSW area,addr 
where: 

area is the address of a two-word EMT argument block 

addr is a pointer to a list of addresses terminated by a zero word. The 
addresses in the list must be even and be one of the following: 

a. in the range 2-476 

b. in the user job area 

c. in the I/O page (addresses 
160000-177776) 
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Request Format: 
RO -* area: 



-66 



addr 



Errors: 



Code Explanation 

One or more of the conditions specified by addr was violated. 



XT' ^1„. 



.TITLE CNTXSU.MAC 

.CNTXSH - This is an ei-cemple in the use of the .CNTXSW reauest. 

In this examplet s .CNTXSU reouest is used to specify thst location 20 

and 22 <IOT vectors) and certain necessary EAE registers be conte^tt 

switched. This allows both Jobs to use lOT and the EAE simultaneously 
yet independently. 

.HCALL .CNTXSU. .PRINT? .EXIT 



start: .CNTXSU *AREA.*SULIST 





BCC 


1% 




•PRINT 


♦ADDERR 




.EXIT 




1»J 


.PRINT 
.EXIT 


♦CNTOK 


SULIST! 


.WORD 


20 




.UORD 


22 




.UORD 


177302 




.UORD 


177304 




.UORti 


177310 




.UORD 





area: 


.BLKU 


2 


adderr; 


.ASCIZ 


/? .CNT 


cntok: 


.ASCIZ 


/.CNTXS 




.ENE! 


START 



j Issue the .CNTXSW reauest 

iBranch if successful 

JAddress errortshould not occur) 

JExit the program 

jAcknowledae success with a message 

jthen exit the program 

.Addresses to include in context switch 
;iOT S EAE vectors. . . 
iEAE registers. . . 



fList terminator !!! 



JEMT argument block 



/? .CNTXSU Addressing Error ?/ 



2.7 .CRAW (XM Only) 



The .CRAW request defines a virtual address window and optionally maps it 
into a physical memory region. Mapping occurs if you set the WS.MAP bit in 
the last word of the window definition block before you issue .CRAW. Since 
the window must start on a 4K word boundary, the program only has to 
specify which page address register to use and the window size in 32-word 
increments. If the new window overlaps previously defined windows, those 
windows are eliminated before the new window is created (except the static 
window reserved for a virtual program's base segment). 

Macro Call: .CRAW area[,addr] 



where: 



area is the address of a two-word EMT argument block 
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addr is the address of the window definition block. This argument is 
optional if you have filled in the second word of the area argu- 
ment block with the address pointer 

The window status word (W.NSTS) of the window definition 
block may have one or more of the following bits set on return 
from the request: 

WS.CRW set if address window was successfully created 
WS.VNM set if one or more windows were unmapped to cre- 
ate and map this window 
WS.ELW set if one or more windows were eliminated 



Request Format: 
RO -* area: 

Errors: 



36 



addr 



Code Explanation 

Window alignment error: the new window overlaps the static 
window for a virtual job. The window is too large or W.NAPR is 
greater than 7. 

1 An attempt was made to define more than seven windows in 
your program. You should eliminate a window first (.ELAW), 
or redefine your virtual address space into fewer windows. 

If the WS.MAP bit was set in the window definition block status word, the 
following errors can also occur: 



Code 

2 

4 

Example: 



Explanation 

An invalid region identifier was specified. 

The combination of the offset into the region and the size of the 
window to be mapped into the region is invalid. 



• TITLE XMCOF-Y 

h 

This is an en3iriFle in the use of the RT-11 Extended He«or« recsuests. 
The proaran is a file copy with verify utility that uses extended 
memory to implement Ik transfer buffers. The example utilizes most 
the Extended Memory reouests and demonstrates other proarammina 
technioues useful in utilizing the reouests. 



.NLIST 

•MCALL 

.MCALL 

JSU 

J.VIRT 

ERRBYT 

APR 

APRl 

BUF 

BUFl 

CORSIZ 

PAGSIZ 



BEX 

.UNMAP, 

.RDBBKj 



ELRGi .ELAUr .CRRDt .CRAW. .MAPi .PRINT. .EXIT. .CLOSE 
UDEBK. .TTYOUT, .WDBDF. .RDBDF. .CS16EN, .READU, .WRITU 



44 

2000 

52 



UDB+W.NBAS 
UIiBl+U.NBAS 
40VA. 
CORSIZ/256. 



iJSU location 

(Virtual Job bit in JSW 

(Error byte loacstion 

rPAR/PDR for 1st windou 

! • • 2nd 

(Virtual addr of 1st buffer 

( ■ ' ■ 2nd 

(Size of buffer in words 

(Pase size in blocks 
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URNin 


UDB+U.NRID 




URNini 


UriBl+U.NRID 




.ASECT 






= JSU 






.UORIl 


J.VIRT 




.PSECT 






.uhbdf 






•RDBDF 




START! 


.CSI6EN 


♦ENDCRE,»BEFLT.*0 




ECS 


START 




INCB 


ERRNO 




.CRRG 


*CAREA.*RDB 




BCC 


10$ 




JMP 


ERROR 


10$: 


MOU 


RDBiURNID 




INCB 


ERRNO 




.CRAU 


*CAREA.*UDB 




BCC 


20$ 




JMP 


ERROR 


20$: 


INCB 


ERRNO 




.MAP 


*CAREAf*UDB 




BCC 


30$ 




JMP 


ERROR 


30$: 


CLR 


Rl 




MOV 


♦C0RSIZ>R2 




INCB 


ERRNO 


read: 


.READW 


*RAREA.*3.BUF.R2iRl 




BCC 


WRITE 




TSTB 


e*ERRBYT 




BEB 


PASS2 




JMP 


ERROR 


write: 


MOV 


R0rR2 




.URITU 


*RAREA.*0,BUF»R2iRl 




BCC 


ADD IT 




INCB 


ERRNO 




JMP 


ERROR 


audit: 


Aim 


♦PAGSIZ.Rl 




BR 


READ 


PASS2; 


INCB 


ERRNO 




.CRRG 


♦CAREA.tRDBl 




BCC 


35$ 




JMP 


ERROR 


35$: 


MOV 


RDBl-URNIDl 



Reaion ID addr of 1st region 
■ 2nd 

Assemble in the Virt Job Bit 

Make this a "virtual' Job 
Start code now 

Create Window Def Blk Sunbols 
Reaion * 

Get filespecsf handlers> open files 

Branch if error 

ERR = Ix 

Create 3 reaion 

Branch if successful 

Report error (JMP due to ranSe ! ) 

Move reaion id to Window Def Blk 

ERR = 2x 

Create window. . . 

Branch if no error 

Report error. . . 

ERR = 3x 

Explicitly nap window... 

Branch if no error 

Report error 

Rl = RTll Block * for I/O 

R2 = * of words to read 

ERR = 4x 

Try to read 4k worth of blocks 

Branch if no error 

EOF? 

Branch if yes 

Must be hard error» report it 

R2 = size of buffer Just read 

Write out the buffer 

Branch if no error 

ERR = 5x 

Report error 

Adjust block * 

Then so set another buffer 

ERR = Ax 

Create a re^iori 

Branch if no error 

Report error 

Get reaion id to window def blk 



i* EXAMPLE USING THE .CRAW REQUEST DOING * 
i* IMPLIED .MAP REQUEST. * 



VERIFYl 



getblk; 



40$: 



50$: 



70$: 



ENDIT! 



INCB ERRNO 

.CRAU tCAREAitUDBl 

BCC VERIFY 

JMP ERROR 

; INCB ERRNO 

CLR Rl 

MOV *C0RSIZ>R2 

.READW *RAREA,»3.BUF1,R2.R1 

BCC 40$ 

TSTB e*ERRBYT 

BEQ ENDIT 

JMP ERROR 

MOV R0fR2 

.READW *RAREAf*0iBUF.R2>Rl 

BCC 50$ 

INCB ERRNO 

JMP ERROR 

MOV BUFjR4 

MOV BUF1fR3 

CMP (R4)+r(R3)+ 

BNE ERRDAT 

DEC R2 

BNE 70$ 

ADD *PAGSIZiRl 

BR GETBLK 

.PRINT tENDPRG 



;ERR = 7x 

iCreate window usina implied .MAP 

SBranch if no error 

iReport error 

iERR = 8x 

fRl = RTll block * saain 

iR2 = 4k buffer sire 

(Try to aet 4K worth of input file 

jBranch if no error 

(EOF? 

jBranch if yes 

jReport hard error 

>R2 = size of buffer read 

!Tr« to aet saae size fro* output file 

(Branch if no error 

;err = 9x 

JRePort error 

56et output buffer address 

(Get input buffer address 

fVerify that data is the saae 

JIt's notr report error 

(Are we finished? 

JBranch if we aren't 

iAdJust block # for paae size 

(Go aet another buffer pair 

^Announce we're finished 
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XCLOS! 



ERROR! 



ERRDAT! 



RDB! 

udb: 

RDBi: 

woBi: 

CAREA! 
RAREA! 

deflt; 

ENDPRG! 

err: 

ERRNO: 

ERRBUF! 

ENDCRE 



.CLOSE 

•UNMAP 

.ELAU 

.ELRG 

.ELRG 

.EXIT 

MOVB 

ADIr 

MOVB 

.PRINT 

BR 

.PRINT 

BR 

.RDBBK 
.UDBBK 
.RBBBK 
.UDBBK 

.BLKU 

.BLKU 

.WORD 

.ASCIZ 

.ASCII 

.ASCIZ 

.ASCIZ 



.END 



*0 

#CAREA.*UnB 
*CAREAf*UDB 
*CAREA>*RDB 
«CAREA>*R0B1 



StERRBYT.RO 

*'0.R0 

R0,ERRN0+1 

♦ ERR 

XCLOS 

♦ERRBUF 

XCLOS 



fClose output file 

jExplicitla unasp 1st window 

JExplicitlu elininate 1st window 

lElinimste 1st resliDn 

fUnnspf el iainste 2nd window % reaion 

(Exit proaram 

iMske error bate code 2nd diait 

rof error code. . . 

fPut it in error itessaae 

fPrint it. . . 

fGo close output file 

jReport verify failed... 

JGo close output file 



CORSIZ/32. i.RDDBK defines Region Def Blk 

APRjCORSIZ/32. J.UDDBK defines Window Def Blk 

CORSIZ/32. rDefine 2nd region ssme wsu 

APRl,C0RSIZ/32.,0,0rCGRSIZ/32.tUS.MAP f and 2nd Window 

rtbut with mappina status set!) 
JEMT araument blocks 

O'O SNo default extensions 

End of XM Example Program */ 
Reouest or I-O Error ♦ / 

ts Verification Error?/ 

'For CSIGEN - XM handlers loaded ! 



6 

0.0 
/ * 
/?XM 
/OO/ 

/?D3 



START 



2.8 .CRRG (XM Only) 



The .CRRG request directs the monitor to allocate a dynamic region in physi- 
cal memory for use by the current requesting program. 

Macro Call: .CRRG area[,addr] 



where: 



area 
addr 



is the address of a two-word EMT argument block 

is the address of the region definition block for the region to be 
created 



Request Format: 
RO -> area 

Errors: 



36 



addr 



Code Explanation 

6 No region control blocks are available. You eliminate a region 
to obtain a region control block (.ELRG), or you can redefine 
your physical address space into fewer regions. 

7 A region of the requested size cannot be created because not 
enough memory is available. The size of the largest available 
region is returned in RO. 

10 An invalid region size was specified. A value of 0, or a value 
greater than 96K words, is invalid. 
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Example: 

Refer to example for the .CRAW request. 



2.9 .CSIGEN 



The .CSIGEN request calls the Command String Interpreter (CSI) in general 
mode to process a standard RT-11 command string. In general mode, file 
.LOOKUP and .ENTER requests as well as handler .FETCH requests are 
performed. 

The .CSIGEN request gets the command string dev: output- filespec^dev: 
input-filespec/options into the program, and the following operations occur: 

1. The handlers for devices specified in the command line are fetched. 

2. .LOOKUP and/or .ENTER requests on the files are performed. 

3. The option information is placed on the stack. See the end of this section 
for a description of the way option information is passed. Note that this 
call always puts at least one word of information on the stack. 

When called in general mode, the CSI closes channels 0-10 (octal). 

.CSIGEN loads all necessary handlers and opens the files as specified. The 
area specified for the device handlers must be large enough to hold all 
the necessary handlers simultaneously. If the device handlers exceed the 
area available, your program can be destroyed. (The system, however, is 
protected.) 

The three possible output files are assigned to channels 0, 1, and 2, and the six 
possible input files are assigned to channels 3 through lO(octal). A null speci- 
fication causes the associated channel to remain inactive. For example, the 



i.\^±X\J * 



* »LP:=F1 »F2 

causes channel to be inactive since the first specification is null. Channel 1 
is associated with the line printer, and channel 2 is inactive. Channels 3 and 4 
are associated with two files on DK:, while channels 5 through 10 are inactive. 
Your program, can determine whether a channel is inactive by issuing a 
.WAIT request on the associated channel, which returns an error if the 
channel is not open. 

Macro Call: .CSIGEN devspc,defext,cstrng[,linbufl 

where: 

devspc is the address of the memory area where the device handlers 
(if any) are to be loaded 

defext is the address of a four-word block that contains the Radix-50 
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default file types. These file types are used when a file is 
specified without a file type (see Note 1) 

cstrng is the address of the ASCIZ command string or a if input is 
to come from the console terminal. (In an FB or XZ environ- 
ment, if the input is from the console terminal, an .UNLOCK 
of the USR is automatically performed while the string is 
being read, even if the USR is locked at the time.) If the string 
is in memory, it must not contain a HiKlf) (octal 15 and 12), 
and must terminate with a zero byte. If the cstring field is 
blank, input is automatically taken from the console terminal. 
This string, whether in memory or entered at the console, 
must obey all the rules for a standard RT-11 command string 

linbuf is the storage address of the original command string. This is 
a user-supplied area, 81 decimal bytes in length. The com- 
mand string is terminated with a zero byte instead of EH) © 
(octal 15 and 12). If this argument is omitted, the input com- 
mand string is not copied to user memory 

On return, RO points to the first available location above the handlers, the 
stack contains the option information, and all the specified files have been 
opened. 

Notes: 

1. The four- word block pointed to by defext is arranged as: 

Word 1: default file type for all input channels 

Words 2,3,4: default file types for output channels 0,1, and 2, re- 
spectively 

If there is no default for a particular channel, the associated word must 
contain 0. All file types are expressed in Radix-50. For example, the 
following block can be used to set up default file types for a macro assem- 
bler: 

DEFEKT: .RAD50 "MAC" 

.RAD50 "OBJ" 

.RAD50 "LST" 

.WORD 

In the command string: 

♦ DTO: ALPHA tDT 1 : 5ETA = DT2 : INPUT 

the default file type for input is MAC; for output, OBJ and LST. The 
following cases are valid: 

*DTO : OiJTPUT = 
*DT2:INPUT 

In other words, the equal sign is not necessary if only input files are 
specified. 

2. An optional argument (linbuf) is available in the .CSIGEN format that 
provides the user with an area to receive the original input string. The 
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input string is returned as an ASCIZ string and can be printed through a 
.PRINT request. 

3. The .CSIGEN request automatically takes its input line from an indirect 
command file if console terminal input is specified {cstring = 0) and 
the program issuing the .CSIGEN is invoked through an indirect 
command file. 



Errors: 



If CSI errors occur and input was from the console terminal, an error 
message uescriuiiig uie lauiL is piuitcu uu tuc bciiiiuiai anu luc \_/ox 
retries the command. If the input was from a string, the carry bit is set 
and byte 52 contains the error code. In either case, the options and 
option-count are purged from the stack. The errors are: 

Code Explanation 

Invalid command (such as bad separators, invalid file names, 
and commands that are too long). 

1 A device specified is not found in the system tables. 

2 A protected file of the same name already exists. A new file was 
not opened. 

3 Device full 

4 An input file was not found in a .LOOKUP. 



Example: 

•TITLE CSIGEN, MAC 
+ 
.CSIGEN - This is sn ejooiple in the use of the .CSIGEN reciuest. 
The e>!3iiiple is s sinsle file copb proSram. The file specs are 
input from the console teminalj and the input S output files opened 
via the General mode of the CSI. The file is copied usin3 synchronous 
I/0> and the output file is made permanent vis the .CLOSE reouest. 

.MCALL .CSIGEN. .READW. , PRINT ,. EXIT f . WRITW. . CLOSE ». SRESET 

iError Bute Loacation 

start: .CSIGEN *DSPACE»«riEXT iGet string from terminal 

fRO has first free location 

finput block * 

fEMT Argument list 
read: .READU R5j*3»BUFF.*256. .INBLK JResd a block on Channel 3 

fBranch if no errors 

JEOF error ? 

i Yes . . > 

JRO => Read Error Hessaae 
1$; .PRINT JPrint the message 

iClear RO for hard exit 

JExit the proSram 
2*: .URITW R5»#0fBUFF.#256. jINBLK iWrite the block Just read 

JSranch if no error 

»R0 => Write error message 

SBrsnch to output the messaSe 
NOERR! INC INBLK fOtherwisei increment block * 

Jand loop to read next block 
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ERRBYT= 


52 


.CSIGEN 


*DSPACEf«riEXT 


Moy 


ROfBUFF 


CLR 


INBLK 


MOV 


*l:st.R5 


.READU 


R5»*3»BUFF.*256 


BCC 


2« 


TSTB 


e*ERRBYT 


BEQ 


EOF 


HOV 


♦INERR.RO 


.PRINT 




CLR 


RO 


.EXIT 




.URITW 


R5.#0fBUFF.#256 


BCC 


NOERR 


MOV 


♦UTERRfRO 


BR 


1« 


INC 


INBLK 


BR 


READ 



EOF? .CLOSE »0 

.CLOSE #3 
.SRESET 
.EXIT 

dext: <uord o>o>o>o 

buff: .word 

inblk: .word o 

list: .blkw 5 



DSPACE= 



JEnd-of-File. . .CLose output channel 
rAnd input channel 
vRelesse h3ndler(s> fron nemoriii 
»Exit the proSrsm 

rNo default extensions 

JI/0 Buffer stsrt 

SRelstive block to read/write 

jEMT arauaent list 



inerr: .asciz 
uterr: .ftsciz 

.EVEN 



/? Input error ?/ 
/? Output error ?/ 



iHandler<s) can be loaded starting here 



.END 



start 



2.9.1 Passing Option information 

In both general and special modes of the CSI, options and their associated 
values are returned on the stack. A CSI option is a slash (/) followed by any 
character. The CSI does not restrict the option to printing characters, al- 
though you should use printing characters wherever possible. The option can 
be followed by a value, which is indicated by a : separator. The : separator is 
followed by an octal number, a decimal number, or by one to three alphanu- 
meric characters, the first of which must be alphabetic. Decimal values are 
indicated by terminating the number with a decimal point (/N:14.). If no 
decimal point is present, the number is assumed to be octal. Options can be 
associated with files. For example, the command string 

*DK :FOO/A »DT4 : F ILE , OBJ/ft : 100 



has two A options. The first is associated with the input file DK:FOO. The 
second is associated with the input file DT4:FILE.0BJ and has a value of 
lOO(octal) . The format of the stack output of the CSI for options is as follows: 



Word# 

1 
(top of 
stack) 



Value 

N 



uption cnaracter 
and file number 



Meaning 

Number of options found in command 
string. If N=0, no options were found. 



Even byte = seven -bit 
character 



ASCII option 



Option value 
or next option 



Bits 8-14 = number (0-10) of the file 
with which the option is as- 
sociated 

Bit 15 = 1 if the option had a value 
= if the option had no value 

If bit 15 of word 2 is set, word 3 contains the 
option value. If bit 15 is not set, word 3 con- 
tains the next option character and file num- 
ber, if any. 
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For example, if the input line to the CSI is 

»FILE/B:ZO, ,FIL2/E = DT3: INPUT/X : SY : 20 

on return, the stack is: 

Stack Pointer -► 4 Three options appeared (X option has two 

values and is treated as two options). 
101530 Last option=X; with file 3, has a value. 

20 Value of option X=20 (octal) 
±ij±uo\j i\cAt uptiuii =-'V, wim lue o, nas a vaiue. 
075250 Next value of option X=RAD50 code for SY. 

505 Next option=E; associated with file 1, no value. 
100102 Option=B; associated with file and has a 
value of 24 
24 (octal). 

As an extended example, assume the following string was input for the CSI in 
general mode: 

*FILEC8. 3 ,LP: tSY : F I LE2 [ 20 , 3 = PC : ,DT1 :IN1/B »DT2: IN2/M:7 

Assume also that the default file type block is: 

DEFEXT: . RAD50 'MAC flNIPUT FILE TYPE 

.RAD50 'OPl' ;FIRST OUTPUT FILE TYPE 

,RAD50 '0P2' ;SECOND OUTPUT FILE TYPE 

.RAD50 '0P3-' STHIRD OUTPUT FILE TYPE 

The results of the above CSI call are as follows: 

1. An eight-block file named FILE. OPl is entered on channel on device 
DK:; channel 1 is open for output to the device LP:; a 20-block file named 
rijjji^. Oi-o IS eniereu on tne system aevice on cnannei z. 

2. Channel 3 is open for input from paper tape; channel 4 is open for input 
from a file INI. MAC on device DTI:; channel 5 is open for input from 
IN2.MAC on device DT2:. 

3. The stack contains options and values as follows: 

Contents Explanation 

2 Two options found in string. 

102515 Second option is M, associated with channel 5; has a value. 

7 Numeric value is 7 (octal). 

2102 Option is B, associated with channel 4; has no value. 

If the CSI were called in special mode, the stack would be the same as for the 
general mode call, and the descriptor table would contain: 

OUTSPC: 15270 ;.RAD50 'DK' 
233Ba i.RADSO 'FIL' 
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17500 


i .RAD50 




E' 


GO 137 


i .RAD50 




DPI ' 


10 


;length 


OF 


8 BLOCKS (DECIMAL 


ilSGOO 


; .RAD50 




LP' 





;no name 


OR LENGTH SPECIFIED 





























75250 


; ,RAD50 




'SY' 


233Ga 


;.RAD50 




'FIL' 


22100 


; .RAD50 




'E2' 


GOiai 


; .RAD50 




'0P3' 


24 


;length 


OF 


20 (DECIMAL) 


G2170 


i.RADSO 




'PC 






;no nahe 


OR LENGTH SPECIFIED 



1G077 


; ,RAD50 




'DTI ' 


35217 


J.RAD50 




'INI' 





; .RAD50 






50553 


;,RAD50 




■MAC 


IBIOO 


; ,RAD50 




'DT2' 


35220 


; .RAD50 




'IN2' 





;.RAD50 






50553 


;,RAD50 




'MAC 












(12 more zero words are returned) 

Keyboard error messages that can occur when input is from the console key- 
board include: 



Message 

?CSI-F-Illegal command 
?CSI-F-file not found 
?CSI-F-Device full 
?CSI-F-Illegal device 
?CSI-F-Protected file 



Meaning 

Syntax error. 
Input file was not found. 
Output file does not fit. 
Device specified does not exist. 
Output file specified already 
exists and is protected. 



Notes: 

1. In many cases, your program does not need to process options in CSI calls. 
However, you could inadvertently enter options at the console. In this 
case, it is wise to save the value of the stack pointer before the call to the 
CSI, and restore it after the call, so that no extraneous values are left on 
the stack. Note that even a command string with no options causes a word 
to be pushed onto the stack. This word indicates the number of options to 
follow. 

2. Under an FB monitor, calls to the CSI that require console terminal input 
always do an implicit .UNLOCK of the USR while the string is being 
gathered. I'his should be kept in mind when using .LOCK calls. 
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2.10 .CSISPC 



The .CSISPC request calls the Command String Interpreter in special mode 
to parse the command string and return file descriptors and options to the 
program. In this mode, the CSI does not perform any .CLOSE, .ENTER, 
.LOOKUP, or handler .FETCH requests. 

Options and their associated values are returned on the stack. The optional 
argument (linbuf) can provide your program with the original command 
string. 

.CSISPC automatically takes its input line from an indirect command file if 
console terminal input is specified (cstrng = #0) and the program issuing the 
.CSISPC is invoked through an indirect command file. 

Note that in a foregroundA)ackground environment, calling the CSI performs 
a temporary and implicit .UNLOCK while the command line is being read. 

Macro Call: .CSISPC outspc,defext,cstrng[,linbuf] 



where: 



outspc is the address of the 39-word block to contain the file descrip- 
tors produced by .CSISPC. This area can overlay the space 
allocated to cstring, if desired 

defext is the address of a four-word block that contains the Radix- 50 
default file types. These file types are used when a file is 
specified without a file type 

cstrng is the address of the ASCIZ input string or a #0 if input is to 
come from the console terminal If the string is in memory, it 
must not contain a SH) © (octal 15 and 12), and must termi- 
nate with a zero byte. If cstrng is blank, input is automatically 
taken from the console terminal or indirect file, if one is active 

linbuf is the storage address of the original command string. This is a 
user-specified area, 81 bytes in length. The command string is 
terminated with a zero byte instead of (Rll) O (octal 15 and 12) 

Notes: 

1. The file description consists of 39 words, comprising nine file descriptor 
blocks (five words for each of three possible output files; four words for 
each of six possible input files), which correspond to the nine possible files 
(three output, six input). If any of the nine possible file names are not 
specified, the corresponding descriptor block is filled with zeroes. 

2. The five- word blocks hold four words of Radix-50 representing 
dev.file.type, and one word representing the size specification given in 
the string. (A size specification is a decimal number enclosed in square 

#DT3:LIST.MACC15]=PC: 
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Using special mode, the CSI returns in the first five-word slot: 



16101 
46173 
76400 
50553 
00017 



Radix-50 for DT3 
Radix-50 for LIS 



Radix-50 for 
Radix-50 for 



T 

MAC 



Octal value of size request 

In the fourth slot (starting at an offset of 36 bytes (octal) into outspc), the 
CSI returns: 

62170 Radix-50 for PC 

No file name 
specified 

No file type given 

Since this is an input file, only four words are returned. 

Errors: 

Errors are the same as in general mode except that invalid device speci- 
fications are checked only for output file specifications with null file 
names. Since .LOOKUP and .ENTER requests are not done, the valid 
error codes are: 

Code Explanation 

Invalid command line. 

1 Invalid device. 

Example: 

.TITLE CSISPC.MAC 

.CSISPC - This is 3n example in the use of the .CSISPC reouest. 
The example uses the "special' raode of CSI to set an input 
specification from the console terninslf then uses the .DSTATUS 
reauest to determine if the output device's handler is loaded* 
if not» 3 .FETCH reouest is issued to load the handler into 
ffleaorvi. Finally a .DELETE reauest is issued to delete the specified 
file. 

.MCALL .DSTATUS. .PRINT .. EXIT, . FETCH i . CSISPC. . DELETE 

JUse .CSISPC to Set output spec 

» Check on the output device 

J (CSISPC catches illeaal devices!) 

SSee if the device is resident 

rBranch if alread^j loaded 

ilt's not loaded. . ibrins it into memory 

JEranch if successful 

SFeteh failed. . .print error nessaSe 

Jthen exit prosrani 

i Now delete the file 
JBranch if successful 
JPrint error nesss^e 
JThe tra aaain 

•Acknowledge successful deletion 
fthen exit prosram 

iEHT Ar^unent block 

rBlock for status 

fNo default extensions 



start: 


.CSISPC 


*OUTSPr#DEFEXT 




.DSTAT 


♦STAT.tOUTSP 




TST 


STAT+4 




BNE 


2» 




.FETCH 


*HANLOD,*INSPEC 




BCC 


2» 




.PRINT 


♦FEFAIL 




.EXIT 




2«; 


•DELETE 


*AREA>«0>*INSPEC 




BCC 


3$ 




.PRINT 


♦NOFIL 




BR 


START 


3»J 


.PRINT 
.EXIT 


♦FILDEL 


area: 


.BLKU 


2 


stat: 


.BLKW 


4 


defext: 


.WORD 


O.OjOrO 
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FEFAILJ .ASCIZ /?. FETCH Failed?/ fFetch fsiled messsSe 

NOFIL! .ASCIZ /TFile Not Found?/ JFile not found 

FILDEL: .ASCIZ /IFlle Deleted!/ fDelete acknowledgement 
.EVEN iFiy. boundary 

QUTSP = . SOutput spec aoes here 

INSPEC = .+36 J Input spec is here 

HANLOD = .+39. fHandler loaded here (if necessary) 

.END START 



OCTAT ICO <«nH YM rtnlM\ 

This request furnishes you with information about a channel. 

Macro CaU: .CSTAT area,chan,addr 

where: 

area is the address of a two-word EMT argument block 
chan is the number of the channel about which information is desired 
addr is the address of a six-word block to contain the status 

Request Format: 
RO -> area: 
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addr 



Notes: 

The six words passed back to the user correspond to the following six points of 
information: 

1. Channel status word (see the RT-11 Software Support Manual for details) 

2. Starting block number of file (0 if sequential-access device, or if channel 
was opened with a non-file-structured .LOOKUP or .ENTER) 

3. Length of file (no information if non-file-structured device, or if channel 
was opened with a non-file-structured .LOOKUP or .ENTER) 

4. Highest relative block written since file was opened (no information 
if non-file-structured device). This word is maintained by the 
.WRITE/. WRITC/.WRITW requests 

5. Unit number of device with which this channel is associated 

6. Radix-50 of the device name with which the channel is associated (this is 
a physical device name, unaffected by any user name assignment in 
effect). 

Errors: 

Code Explanation 

The channel is not open. 
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Example: 



.TITLE CSTAT.MAC 
J + 

} .CSTAT - This is an example in the use of the .CSTAT reouest. 
f In this ex3i»ple» .CSTAT is used to determine the .RAD50 
} representation of the device with which the channel is associated. 
i — 

.HCALL .CSTAT J . CSIGENj . PRINT j .EXIT 

start: .CSIGEN #DEVSDC»*DEFEXT fOpen files 

.CSTAT *AREA»*Of*AIiDR JGet the status 

jChannel not open 
jpoint to unit ♦ 
fUnit * to RO 
JMake it RADSO 

rGet device name 

f'DEVNAM' has RADSO device name 

JExit the program 

JPrint error message 
fthen exit prosra* 



JFix boundary 

5EMT ara list 

$Area for channel status 

rStoraae for device name 

iHo default extensions 

(Start CSI tables here... 





BCS 


NOCHAN 




MOV 


♦ADDR+10.R5 




MOM 


<R5)+,R0 




ADD 


(PC)+fRO 




. RADSO 


/ 0/ 




ADD 


{R5)>R0 




MOV 


ROfDEVNAM 




.EXIT 




nochan: 


.PRINT 
.EXIT 


*hsg 


msg: 


.ASCIZ 
.EVEN 


/?No Output 


AREA! 


.BLKU 


5 


addr: 


.BLKW 


6 


DEVNAMt 


.UORD 





DEFEXT5 


.WORD 


0»0»0>0 


DEVSDC=, 


» 





.END 



START 



2.12 .CTIMIO (Device Handler Only) 

The .CTIMIO macro cancels the device time-out request in the handler inter- 
rupt service section. It is used when an interrupt occurs to disable the comple- 
tion routine (see .TIMIO). 

If the time interval has already elapsed and the device has, therefore, timed 
out, the .CTIMIO request fails. The completion routine has already been 
placed in the queue. The .CTIMIO call returns with the C bit set when it fails 
because the completion routine was already queued. 

The device time-out feature must have been selected during the system gener- 
ation process. 

Macro Call: .CTIMIO tbk 
where: 

tbk is the address of the seven-word timer block shown in Table 2-1 
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Table 2-1: Timer Block Format 



Offset 


Filled in By 


Contents 



2 
4 
6 

10 

12 

14 


.TIMIO 
.TIMIO 
monitor 
user 

user 

monitor 
user 


High-order time word (expressed in ticks). 

Low-order time word (expressed in ticks). 

Link to next queue element; indicates none. 

Owner's job number; for background job, MAXJOB for fore- 
ground job, and job priority *2 for system jobs. MAXJOB is 
equal to (the number of jobs in the system * 2)-2. The job 
number for the foreground job is 2 in a system without system 
jobs, and 16 for a system with system jobs. The job number is 
set from the queue element. 

Sequence number of timer request. The valid range of sequence 
numbers is from 177400 to 177477. 

-1 

Address of the completion routine to execute if timeout occurs. 
The monitor zeroes this word when it calls the completion rou- 
tine, indicating that the timer block is available for reuse. 



The .CTIMIO macro expands as follows: 



.CTIMIO tbR 



JSR 

.WORD 

.WORD 



R5.@*TIMIT 
tfak - . 
1 



JPOINTER AT END OF HANDLER 
;CODE FOR .CTIMIO 



Example: 

Refer to the example for the .TIMIO request. 



2.13 .DATE 



This request returns the current date information from the system date word 
in RO. The date word returned is in the following format: 

BIT: 15 14 13 ... 10 9 ... 5 4 ... 

MONTH DAY YEAR 

The year value in bits 4-0 is the actual year minus 1972. The day in bits 9 to 5 
is a number from 1 to the length of the month. The month in bits 13 to 10 is a 
number from 1 to 12. 

NOTE 

RT-11 support of month and year rollover is a system genera- 
tion special feature; otherwise, the keyboard monitor DATE 
command must be issued to change the month and year. 
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12 



Macro Call: .DATE 
Request Format: 
RO = 

Errors: 

No errors are returned. A zero result in RO indicates that the user has 
not entered a date. 



Example: 



.TITLE IiATE.HftC 



.DATE - This is 3n eKsnple in the use of the .DATE reouest. 
This ex3aple nsu be 3ssei»bled sepsrstela and linked with 
user written pro^rsns 



input: 


none 








output: 


RO = 


MONTH 


(1-12) 






Rl = 


DAY 


(1-31) 






R2 = 


YEAR 


(Modulus 


100) 


errors: 


RO = 


if r 


TO date er 


itere 



.MCALL .DATE 



date;: 


.DATE 






MOV 


R0,R2 




6EQ 


1» 




BIC 


#"C37rR2 




ADD 


*72.»R2 




MOV 


R0»R1 




ASL 


Rl 




ASL 


Rl 




ASL 


Rl 




SWAB 


Rl 




BIC 


♦"C37.R1 




SUAB 


RO 




ASR 


RO 




ASR 


RO 




BIC 


*"C37>R0 


i«: 


RETURN 





fGet d3te in RO vis .DATE reauest 

fCopa RO 

>If zero* no d3te w3s entered 

>Cle3r 8ll but ■jear bits 

rHske it current sesr 

rCoPU d3te word sdsin 

!6et d3u bits 

ron 3 bute bound3ru... 

f 

>Put dss bits in low order bate 

iCle3r 3ll but dsa bits 

iPut month bits in low bate 

rRidht sdJust 

raonth bits. . . 

rClesr 3ll but nonth bits 

(Return to csllina pro^rs* 



.END 



DATE 



2.14 .DELETE 



The .DELETE request deletes a named file from an indicated device. The 
.DELETE request is illegal for magtapes. The .SERR programmed request 
can be used to allow the program to process any errors. 

Macro Call: .DELETE area,chan,dblk,seqnum 
where: 

area is the address of a three-word EMT argument block 

chan is the device channel number in the range 0-377 (octal) 
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dblk is the address of a four- word Radix-50 descriptor of the file to 

be deleted 

seqnum file number for cassette operations: if this argument is blank, 
a value of is assumed 

Request Format: 

RO ->• area: 



chan 



dblk 



seqnum 



Notes: 

The channel specified in the .DELETE request must not be open when the 
request is made, or an error will occur. The file is deleted from the device, and 
an empty (UNUSED) entry of the same size is put in its place. A .DELETE 
issued to a non-file-structured device is ignored. .DELETE requires that the 
handler to be used be in memory at the time the request is made. When the 
.DELETE is complete, the specified channel is left inactive. 



Errors: 

Code 


1 

2 

3 

Example: 



Explanation 

Channel is active. 

File was not found in the device directory. 

Invalid operation. 

The file is protected and cannot be deleted. 



.TITLE DELETE. MAC 
I- 
.DELETE - This is 3n example in the use of the .DELETE reouest. 
The example uses the "special" mode of CSI to Set sn input 
specification from the console terminal » then uses the .DSTATUS 
reouest to determine if the output device's handler is loaded? 
if notp a .FETCH reouest is issued to load the handler into 
•e*or«. Firv3ll« a .DELETE reouest is issued to delete the specified 
file. 



STARTS 



2*t 



3$: 



.MCALL . DSTATUS » . PRINT » .EXIT . .FETCH. . CSI SPC. . DELETE 



Use .CSISPC to set output spec 
iCheck on the output device 
i(CSISPC catches illeSal devices!) 
iSee if the device is resident 
(Branch if already loaded 
ilt's not loaded. . .brin^ it into memora 
iBranch if successful 
iFetch failed. . .print error message 
ithen exit proarsm 

i Now delete the file 
IBranch if successful 
iPrint error message 
IThe tra asain 

i Acknowledge successful deletion 
Ithen exit program 



.CSISPC 


»OUTSPj*DEFEXT 


.DSTAT 


*STAT.*OUTSP 


TST 


STAT+4 


BNE 


2« 


.FETCH 


#HANL0D,*INSPEC 


BCC 


2« 


.PRINT 


♦FEFAIL 


.EXIT 




.DELETE 


#AREA,»0.»INSPEC 


BCC 


3* 


.PRINT 


♦NOFIL 


BR 


START 


.PRINT 


♦FILDEL 


.EXIT 
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area: .blku 2 
stat? .blku 4 

DEFEXTt .UORD OfO.OfO 



iEMT Ardunent block 

iBlock for status 

$No default extensions 



FEFftlLJ .ASCIZ 
NOFIL: .ASCIZ 

fildel; .ASCIZ 

.EVEN 



/?. FETCH Failed?/ 
/TFile Not Found?/ 
/IFile Deleted!/ 



OUTSP = . 
INSPEC = .+36 
HANLOD = .+39. 

.END START 



'Fetch failed message 
SFile not found 
rDelete acknouledsenent 
JFix boundar!:^ 



fOutput spec Qoes here 

finput spec is here 

f Handler loaded here (if necessary) 



2.15 .DEVICE (FB and XM Only) 

This request allows your program to load device registers with any necessary 
values when the program is terminated. You set up the list of addresses with 
the specified values. Upon issuing an .EXIT request or a CTRL/C from the 
terminal, this list is picked up by the system and the designated addresses are 
loaded with the corresponding values. This function is primarily designed to 
allow your program to turn off a device's interrupt enable bit when the pro- 
gram servicing the device terminates. Successive calls to .DEVICE are al- 
lowed when you need to link requested tables. When the job is terminated for 
any reason, the list is scanned once. At that point, the monitor disables the 
feature until another .DEVICE call is executed. Thus, background programs 
that are reenterable should include .DEVICE as a part of the reenter code. 

The .DEVICE request is ignored when it is issued by a virtual job running 
under the XM monitor. 

Macro Call: .DEVICE area,addr[,link] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of a list of two- word elements, each composed of a 
one-word address and a one-word value to be put at that ad- 
dress. If addr is #0, any previous list is discarded; in this form, 
the argument LINK must be omitted 

link is an optional argument that, if present, specifies linking of 
tables on successive calls to .DEVICE. If the argument is omit- 
ted, the list referenced in the previous .DEVICE request is re- 
placed by the new list. The argument must be supplied to cause 
linking of hsts; however, linked and unlinked list types cannot 
be mixed 



Request format: 

Nonlinking 

RO ->■ area: 



Linking 



14 



addr 



nu -► area: 



14 



addr 
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NOTE 

The list referenced by addr must be either in linking or non- 
linking format. The different formats are shown below. Both 
formats must be terminated with a separate, zero-value word. 
Linking format must also have a zero-value word as its first 
word. 



Nonlinking 

addr: 



address 



address 



value 



Linking 



addr: 







aLuaxcao 



value 



address 



value 



address 



value 



u 



address 



vaiue 







Errors: 

None. 
Example: 

.TITLE DEMICE.MAC 

J + 

f .DEVICE - This is sn e>!8«ple in the use of the .DEVICE reauest. 
i The exsBPle shows how .DEVICE is used to dissble interrupts from 
f a device upon terninstion of the proarsm. In this esse the device 
i is 3 DLll Serial Line Interface. 



.MCALL .DEVICE. .EXIT, .PROTECT! .UNPROTECT .. PRINT 



start: .DEVICE *AREA.#LIST 

.PROTECT ♦AREA, #300 
BCS BUSY 



FINi: 

BUSYS 

AREA! 
LISTt 

BUFFRJ 
NOVEC: 



JSR 

.WORD 

.UORD 



R5,DL11 

128. 

BUFFR 



.UNPROTECT *AREAr*300 

.EXIT 

•PRINT *NOVEC 

.EXIT 

.BLKW 3 

.WORD 176500 

.WORD 

.WORD 



fSetup to disable DLll interrupts on 

} .EXIT or "C"C 

fProtect the DLll vectors 

JBranch if already protected 

SSet UP data to transait over DLll 

iUse DLll xfer routine (see .INTEN e;-;3»ple) 
$ Arauaents . • . Word count 
SData buffer addr 
.Continue processina . . . 

J . . .eventualla to exit proaram 



iPrint error messaae... 

ithen ey.it 

JEMT Arauaent block 

JCSR of DLll 

JStuff it with '0' 

iList terainator 

.Data to send over DLll 
sREPT 8; '8 lines of 32 characters... 

^ASCIZ /Hello DLll ... Are You There ??/ 
.ENDR 
.ASCIZ /TVector already protected?/ * Error aessaae text 



.END 



START 
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2.16 .DRAST (Device Handler Only) 

The .DRAST macro sets up the interrupt and abort entry points, lowers the 
processor priority, and references a global symbol $INPTR, which contains a 
pointer to the INTEN routine in the resident monitor. This pointer is filled in 
by the bootstrap (for a system device) or at .FETCH time (for a data device). 

Macro Call: .DRAST name,pri[,abo] 

where: 

name is the two-character device name 

pri is the priority of the device, and also the priority at which the 

interrupt service code is to execute 

abo is an optional argument that represents the label of an abort 
entry point. If you omit this argument, the macro generates an 
RTS PC instruction at the abort entry point, which is the word 
immediately preceding the interrupt entry point 



Example: 



•TITLE SP.MAC 



SP.MAC - This is en eMsmple of 3 simple, RT-ll device driver to illustrate 
the use of the .DRBEG, .DRAST f .DRFIN, .DREND, .FORK Si .QELDF reouests. 
This driver could be used to output to 3 serial ASCII printer-terminsl 
over a DLll Serial Line Interface. To use this driver as an RT-ll device 
handler, sinply install it vis the INSTALL connand (eS. 'INSTALL SP'). 



•MCALL .DRBEGf .DRAST, . DRFIN , . DREND, .QELDF, .FORK 



.IIF NDF MMG»T, HMG$T=0 

.IIF NDF ERLtG, ERLt6=0 

.IIF NDF TIH$IT, TIMtIT=0 

.IIF NDF SPtVECf SP$VEC=304 

.IIF NDF SPtCSR, SP*CSR=176504 

.IIF NDF SPSPRIr SP$PRI=4 



lOERR = 


1 


SPSTS = 


20000 


SPSIZ = 





.QELDF 




fQ.BLKK = 4 




fQ»CSU = -2 




;q»buff = 4 




$a*UCNT = 6 




.DRBEG 


SP,SP$VEC,SPSI 


•f .WORD 


<SPEND-SPSTRT> 


•f .UORD 





i .UORD 


20000 


i .UORD 


ERL$G+<MMG«T«2 


SSPSTRTSS 




; .UORD 


SPVEC+4 


i .UORD 


SPINT-.,-0340 


JSPCQEtJ.UORD 





iSPLQEEi.UORD 





MOV 


SPCQE,R4 


ASL 


Q*UCNT<R4) 


BCC 


SPERR 


BEQ 


SPDUN 


spret; BIS 


*100,e*SP$CSR 


RETURN 





iDefine these in esse not 
iassenbled with SYSCND.MAC 



fDefine default vector 
JDEfine def3ult CSR addr 
JDefine default device priorits 

JHsrd I/O error bit definition 
JDevice Ststus = Urite onlB 
JDevice Size = (Char device) 

JUse .QELDF to define Q-Ele» offsets 
iAikong others t of interest to us are: 
JOffset to Block ♦ (SPCQE => Q.BLKN) 
JOffset fro« Q.BLKN to CSH pointer 
' ■ ■ • ■ User buffer ptr 
' ■ ■ ■ ' Uord count 



Z. SPSTS 



;Begin driver code with .DRBEG 
JMACRO expansion is... 
(Size of driver (handler) 
JSize of device 
fDevice status (Urite onlu) 
■+<TIH«IT«4> JDefault options 
fBeainnins ef driver 
finterrupt vector 

JOffset to Int SVC rtne t Priorita 
fQueue elenent pointers 
MPoint to 3rd uord in element!) 
»R4 => Current Q-Ele»ent 
;fl3ke word count b«te count 
jA read from 3 write/only device? 
rZero word count.. .Just exit 
SEnable DL-11 interrupt 
SReturn to monitor 
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i INTERRUPT SERVICE ROUTINE 
.DRAST SP.SPtF'RI 



r 


RTS 


PC 


5SPINT! 


tJSR 


R5t@$INPTR 


r 


.WORD 


-C<SPtPRI*"040>S"0340 




MOU 


SPCQE.R4 




TST 


@»SPiCSR 




BMI 


SPRET 




BIC 


*iooie*sp*csR 




.FORK 


SPFORK 


spnxt: 


TSTB 


e*sptcsR 




EPL 


SPRET 




MOVE 


l?Q»BUFF(R4).8*SP*CSR + 2 




INC 


Q*BUFF(R4) 




INC 


QSWCNT(R4) 




BEQ 


SPDUN 




BR 


SPNXT 


SPERR! 


BIS 


*I0ERR.eQtCSU(R4) 


sphun; 


.DRFIN 


SF 


i 


MOy 


PC.R4 


f 


ADD 


*SPCQE-.>R4 


r 


Hoy 


e*54.R5 


r 


JMP 


e"0270(R5) 


spfork: 


.UORD 


OfOi »0 




.DRENIi 


SP 


ftlNPTR 


: t.UORD 





;*fkptr 


1 : .WORD 





! SPEND 


--= . 





JUse .DRAST to define Int Svc Sect. 

iHACRO eKPsnsion. . . 

(Abort Entra Point 

iDo s .INTEN to slert monitor 

fsnd drop processor priority 

!R4 => Q-Element 

iError? 

f Yes. .. 'hens' until resdM 

SDisable interrupts 

I Continue st FORK level 

5Is device ready? 

!No...ao wsit 'till it is 

iXfer bate from buffer to DL-11 

iBuBP the buffer pointer 

•and the word count (it's nesstive!) 

fBrsnch if done 

JTra to output snother character 

!Set error bit in CSU 

jUse .DRFIN to return to Monitor 

(MACRO ejcpansion. . . 

(Calculate PIC addr of current 

iQueue element pointer 

(Put addr of base of RMON in R5 

i Jump to handler completion in monitor 

(Fork Queue Element 

(Use .DREND to end code 

(MACRO expansion... 

(Addr of .INTEN code in RMON 

(Addr of .FORK processor in RMON 

(End of driver 



.END 



2.17 .DRBEG (Device Handler Only) 

The .DRBEG macro sets up the information in block and the first five words 
of the handler. This macro also generates the appropriate global symbols for 
your handler. Before you use .DRBEG, invoke .DRDEF to define xx$CSR, 
xx$VEC, xxDSIZ, and xxSTS (see Section 2.19). 

Macro Call: .DRBEG name 

where: 

name is a two-character device name 
Example: 

Refer to the example for .DRAST. 



2.18 .DRBOT (Device Handler Only) 

The .DRBOT macro sets up the primary driver. A primary driver must be 
added to a standard handler for a data device to create a system device 
handler. The .DRBOT macro invokes the .DREND macro (see Section 2.20) 
to mark the end of the handler so that the primary driver is not loaded into 
memory during normal operations. 
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Macro Call: .DRBOT name,entry,read 
where: 

name is the two-character device name 

entry is the entry point of the software bootstrap routine 

read is the entry point of the bootstrap read routine 

The .DRBOT macro puts a pointer to the start of the primary driver into 
location 62 of the handler file. It puts the length (in bytes) of the primary 
driver into location 64. Location 66 of the handler file contains the offset from 
the start of the primary driver to the start of the bootstrap read routine. The 
.DRBOT macro is called before the .DREND macro that you issue. The code 
for the primary driver is placed between the .DRBOT and .DREND calls. 

Example: 

Refer to the RT-11 Software Support Manual for an example showing 
the use of .DRBOT. 



2.19 .DRDEF (Device Handler Only) 



The .DRDEF macro sets up handler parameters, calls the driver macros from 
the library, and defines useful symbols. 

Macro Call: .DRDEF name,code,stat,size,csr,vec 
where: 

is the two-character device name 



name 
code 

stat 



is the numeric code that is the device identifier value for the 
device 

is the device status bit pattern. The value for stat may use the 
following symbols: 



FILST$ = 100000 
RONLY$ = aoOOO 
WONLY$ = 20000 



SPECL$ = 
HNDLR$ = 
SPFUN$ = 



1 0000 
4 
200 



Size 

csr 

vec 



is the size of the device in 256-word blocks 
is the default value for the device's control and status register 
is the default value for the device's vector 
The .DRDEF macro performs the following operations: 

1. A .MCALL is done for the following macros: .DRAST; .DRBEG- 
.DRBOT; .DREND; .DRFIN; .DRSET; .DRVTB; .FORK; .QELDF. 

2. If the system generation conditionals TIM$IT, MMG$T, or ERL$G are 
undefined in your program, they are defined as zero. If time-out support is 
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selected, the .DRDEF macro does a .MCALL for the .TIMIO and 
.CTIMIO macros. 

3. The .QELDF macro is invoked to define symbohc offsets within a queue 
element. 

4. The symbols listed above are defined for the device status bits. 

5. The following symbols are defined: 

HDERR$=1 ;HARD ERROR BIT IN THE CSW 

EDF$=20000 ;END OF FILE BIT IN THE CSW 

6. The symbol xxDSIZ is set to the value specified in size. 

7. The symbol xx$COD is set to the specified device identifier code. 

8. The symbol xxSTS is set to the value of the device identifier code plus the 
status bits. 

9. If the symbol xx$CSR is not defined, it is set to the default csr value. 

10. If the symbol xxSVEC is not defined, it is set to the default vector value. 

11. The symbols xx$CSR and xx$VEC are made global. 

You should invoke the .DRDEF macro near the beginning of your handler, 
after all handler specific conditionals are defined. 

Example: 

Refer to the RT-11 Software Support Manual for an example showing 
the use of .DRDEF. > 



2.20 .DREND (Device Handler Only) 

The .DREND macro generates the termination table for the termination sec- 
tion of the device handler. 

Macro Call: .DREND name 

where: 

name is the two-character device name 

The generation of the termination table, dependent upon certain conditions, 
is as follows: 

Label Addresses 

$RLPTR: .WORD (SRELOC) 

$MPPTR: .WORD ($MPPHY) 

$GTBYT: .WORD ($GETBYT) 

$PTBYT: .WORD ($PUTBYT) 

SPTWRD: .WORD ($PUTWRD) 

$ELPTR: .WORD ($ERLOG) 
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Label Addresses 

$TIMIT: .WORD ($TIMIO) 

$INPTR: .WORD ($INTEN) 

$FKPTR: .WORD ($FORK) 

The generation of the labels depends upon the special features chosen during 
the system generation process. All the pointers in the termination section are 
initialized when the handler is loaded into memory with the .FETCH request. 
If the device handler is a system device, the pointers are initialized at boot 
time with the addresses shown in the address column. The addresses are 
located within the monitor. The first five addresses are the locations of 
subroutines in the resident monitor that are available to device handlers in an 
extended memory environment. Device I/O time-out service is provided by 
$TIMIO and error logging is provided by $ERLOG. The $INPTR and 
$FKPTR labels are always filled in by a .FETCH or LOAD command. 
Example: 

Refer to the example for .DRAST. 



2.21 .DRFIN (Device Handler Only) 

The .DRFIN macro generates the instructions for the jump back to the moni- 
tor at the end of the handler I/O completion section. The macro makes the 
pointer to the current queue element a global symbol, and it generates posi- 
tion-independent code for the jump to the monitor. When control passes to 
the monitor after the jump, the monitor releases the current queue element. 
Macro Call: .DRFIN name 

where: 

name is the two-character device name 
Example: 

Refer to the example for .DRAST. 



2.22 .DRSET (Device Handler Only) 

The .DRSET macro sets up the option table for the SET command in block 
of the device handler file. The option table consists of a series of four-word 
entries, one entry per option. Use this macro once for each SET option that is 
used. When used a number of times, the macro calls must appear one after 
another. 

Macro Call: .DRSET option,val,rtn[,mode] 
where: 

option is the name of the SET option, such as WIDTH or CR. The 
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name can be up to six alphanumeric characters long and 
should not contain any embedded spaces or tabs 

val is a parameter that is passed to the routine in Register R3. It 

can be a numeric constant, such as minimum column width, 
or an entire instruction that is substituted for an existing one 
in block 1 of the handler. It must not be a zero. 

rtn is the name of the routine that modifies the code in block 1 of 

the handler. The routine must follow the option table in block 
zero and m.ust not go above address 776 

mode is an optional argument to indicate the type of SET parame- 
ter. A NO indicates that a NO prefix is valid for the option. 
NUM indicates that a decimal numeric value is required. 
OCT indicates that an octal numeric value is required. Omit- 
ting this argument indicates that the option takes neither a 
NO prefix nor a numeric argument 

The .DRSET macro does an .ASECT and sets the location counter to 400 for 
the start of the table. The macro also generates a zero word for the end of the 
table and leaves the location counter there. Thus routines to modify codes are 
placed immediately after the .DRSET calls in the handler, and their location 
in block zero of the handler file is made certain. 

Example: 

Refer to the RT-11 Software Support Manual for an example of 
.DRSET. 



2.23 .DRVTB (Device Handler Only) 

multi-vector device. The table entries contain the vector location, interrupt 
entry point, and processor status word. You must use this macro once for each 
device vector. The .DRVTB macros must be placed consecutively in the de- 
vice handler between the .DRBEG macro and the .DREND macro. They must 
not interfere with the flow of control within the handler. 

Macro Call: .DRVTB name,vec,int[,ps] 

where: 

name is the two-character device name. This argument must be 
blank except for the first-time use of .DRVTB. 

vec is the location of the vector, and must be between and 474 

int is the symbolic name of the interrupt handimg routme. xt must 

appear elsewhere in the handler code. It generally takes the 
form ddINT, where dd represents the two-character device 
name 



Programmed Request Description and Examples 2-35 



ps is an optional value that specifies the low-order four bits of the 

new Processor Status Word in the interrupt vector. This argu- 
ment defaults to zero if omitted. The priority bits of the PSW 
are set to 7 even if you omit this argument 



Example: 



Refer to the RT-11 Software Support Manual for an example of 
.DRVTB, 



2.24 .DSTATUS 

This .DSTATUS request obtains information about a particular device. 

Macro Call: .DSTATUS retspcdnam 

where: 

retspc is the address of a four-word block that stores the status infor- 
mation 

dnam is the address of a word containing the Radix-50 device name 

.DSTATUS looks for the device specified by dnam and, if successful, returns 
four words of status starting at the address specified by retspc. The four words 
returned are as follows: 

Word 1 Status Word 

Bits 0-7: The low-order byte contains a number that identifies the 
device in the system. The values are currently defined in 
octal as follows: 

= RK05 Disk 

1 = TCll DECtape 

2 = Reserved 

3 = Line Printer 

4 = Console Terminal or Batch Handler 

5 = RL01/RL02 Disk 

6 = RX02 Diskette 

7 = PCll High-speed Paper Tape Reader and Punch 

10 = Reserved 

11 = TUlO Magtape 

12 = RFll Disk 

13 = TAll Cassette 

14 = Card Reader (CRll.CMll) 

15 = Reserved 

16 = RJS03/RJS04 Fixed-head Disk 

17 = Reserved 

20 = TJU16 Magtape 

21 = RP02/RP03 Disk 

22 = RXOl Diskette 

23 = RK06/RK07 Disk 



-36 Programmed Request Description and Examples 



24 = Reserved 

25 = Null Handler 
26-30 = Reserved (DECnet) 

31-33 = Reserved (CTS-300,LQ,LR,LS) 

34 = TU58 DECtape II 

35 = TSll Magtape 

36 = PDT-1 1/130 

37 = PDT-1 1/150 

40 = Reserved 

41 = Serial Line Printer Handler (LS) 

42 = Message Queue Handler (MQ) 

Bit 10: 1= Handler accepts .SPFUN requests (for example, MT, 
CT, DX) 
0= No .SPFUN requests accepted 

Bit 11: 1= Enter handler abort entry every time a job is aborted 
0= Handler abort entry taken only if there is an active 
queue element belonging to aborted job 

Bit 12: 1= Non RT-11 directory-structured device (magtape, cas- 
sette) 

Bit 13: 1= Write-only device (line printer, serial line printer) 

Bit 14: 1= P^ad-only device (card reader, paper tape reader) 

Bit 15: 1= Random-access device (disk, DECtape) 

0= Sequential-access device (line printer, paper tape, card 
reader, magtape, cassette, terminal) 

Word 2 Handler Size 

The size of the device handler in bytes. 

W^ord 3 Load Address +6 

Non-zero implies the handler is now in memory: zero implies that it 
must be fetched before it can be used. The address returned is the load 
address of the handler +6. 

Word 4 Device Size 

The size of the device (in 256-word blocks) for block-replaceable de- 
vices; for sequential-access devices. The last block on the device is the 
device size -1. 

The device name can be a user-assigned name. .DSTATUS information is 
extracted from the device handler. Therefore, this request requires the han- 
dler for the device to be present on the system device and installed on the 
system. 



Errors: 



Code Explanation 

Device not found in tables. 
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Example: 



.TITLE nSTAT.MAC 

h 

.DSTATUS - This is an exsnP'le in the use of the .DSTATUS reauest. 
The exsMPle uses the "special" mode of CSI to set an input 
specification from the console terninal? then uses the .DSTATUS 
reauest to determine if the output device's handler is loaded* 
if notf s .FETCH reauest is issued to load the handler into 
nemoru. Finally a .DELETE reauest is issued to delete the specified 
file. 



.MCALL .DSTATUS. .PRINT, .EXIT, , FETCH ,. CSISPC ,. DELETE 



iUse .CSISPC to set output spec 

JCheck on the output device 

S(CSISPC catches illegal devices!) 

SSee if the device is resident 

fBranch if already loaded 

jIt's not loaded. . .brins it into meniorB 

J Branch if successful 

SFetch fai led. . .print error message 

jthen exit prosram 

, Now delete the file 
.Branch if successful 
fPrint error message 
.The try aSain 

.Acknowledge successful deletion 
Sthen exit proSram 

jEMT Argument block 

fBlock for status 

INo default extensions 



START! 


.CSISPC 


*OUTSP,»DEFEXT 




.DSTAT 


*STAT,*OUTSP 




TST 


STAT+4 




BNE 


2* 




.FETCH 


♦HANLOD.tlNSPEC 




BCC 


2» 




•PRINT 


♦FEFAIL 




.EXIT 




2*! 


.DELETE 


*AREA.*0.*INSPEC 




BCC 


3* 




.PRINT 


♦NOFIL 




BR 


START 


3*! 


.PRINT 
.EXIT 


♦FILDEL 



area: .blku 2 
stat; .blkw 4 

DEFEXT: .WORD 0,0.0,0 



FEFAILJ .ASCIZ 

nofil: .ASCIZ 

FILDEL5 .ASCIZ 
.EVEN 



/?. FETCH Failed?/ 
/?File Not Found?/ 
/IFile Deleted!/ 



fFetch failed message 
iFile not found 
.Delete acknowledgement 
jFix boundary 



OUTSP = . 
INSPEC = .+36 
HANLOD = ,+39. 

.END START 



.Output spec Qoes here 

.Input spec is here 

fHandler loaded here (if necessary) 



2.25 .ELAW (XM Only) 



The .ELAW request eliminates a virtual address window. An implied unmap- 
ping of the window occurs when its definition block is eliminated. 

Macro Call: .ELAW area[,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block for the window to 
be eliminated 



Request Format: 
RO -► area: 



36 



addr 
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Errors: 

Code Explanation 

3 An invalid window identifier was specified. 
Example: 

Refer to the example for the .CRAW request. 



2.26 .ELRG (XM Only) 



The .ELRG request directs the monitor to eliminate a dynamic region in 
physical memory and return it to the free list where it can be used by other 
jobs. 

Macro Call: .ELRG area [,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the region definition block for the region to be 
eliminated. Windows mapped to this region are unmapped. The 
static region cannot be eliminated 

Request Format: 
RO -► area: 



36 



addr 



Errors: 

Code Explanation 



2 An invalid re^'ion identifier was si^ecified. 
Example: 

Refer to the example for the .CRAW request. 



2.27 .ENTER 



The .ENTER request allocates space on the specified device and creates a 
tentative entry in the directory for the named file. The channel number speci- 
fied is associated with the file. 

Macro Call: .ENTER area,chan,dblk,len,seqnum 

where: 

area is the address of a four-word EMT argument block 

chan is a channel number in the range 0-377 (octal) 

Programmed Request Description and Examples 2-39 



dblk is the address of a four- word Radix-50 descriptor of the file to 

be operated upon 

len is the file size specification. If the argument is omitted, it is 

not set to in area. The must be specified to accomplish 
this. If an argument is left blank, the corresponding location 
in area is assumed to be set 

The value of this argument determines the file length alloca- 
tion as follows: 

either half the largest empty entry or the entire second- 
largest empty entry, whichever is larger. (A maximum 
size for nonspecific .ENTER requests can be patched in 
the monitor by changing resident monitor offset 314.) 

m a file of m blocks. The size, m, can exceed the maximum 
mentioned above. 

-1 the largest empty entry on the device. 

seqnum is a file number for magtape or cassette. Programming for 
specific devices such as magtape or cassettes is discussed in 
detail in Chapter 10 of the RT-11 Software Support Manual. 
For cassette operation, if this argument is blank, a value of 
is assumed. 

For magtape, seqnum describes a file sequence number. The 
action taken depends on whether the file name is given or is 
null. The sequence number can have the following values: 

Rewind the magtape and space forward until the file 
name is found or until logical end-of-tape is detected. If 
the file name is found, an error is generated. If the file 
name is not found, then enter file. If the file name is a 
null, a non-file-structured lookup is done (tape is 
rewound) . 

n Position magtape at file sequence number n if n is 
greater than zero and the file name is not null. 

-1 Space to the logical end-of-tape and enter file 



-2 



Rewind the magtape and space forward until the file 
name is found, or until logical end-of-tape is detected. 
The magtape is now positioned correctly. A new logical 
end-of-tape is implied. 



Request Format: 






area: 



chan 



dblk 



len 



seqnum 



On return from this call, RO contains the size of the area actually allocated for 
use. 
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The file created with an .ENTER request is not a permanent file until a 
.CLOSE request is given on that channel. Thus, the newly created file is not 
available to .LOOKUP, and the channel cannot be used by .SAVESTATUS 
requests. However, it is possible to read data that has just been written into 
the file by referencing the appropriate block number. When the .CLOSE to 
the channel is given, any existing permanent unprotected file of the same 
name on the same device is deleted and the new file becomes permanent. 
Although space is allocated to a file during the .ENTER operation, the actual 
length of the file is determined when .CLOSE is requested. 

Each job can have up to 256 files open on the system at any time. If required, 
all 256 can be opened for output with the .ENTER function. 

When an .ENTER request is made, the device handler must be in memory. 
Thus, a .FETCH should normally be executed before an .ENTER can be 
done. 

Notes: 

When using the zero-length feature of .ENTER, keep in mind that the space 
allocated is less than the largest empty space. This can have an important 
effect in transferring files between devices (particularly DECtape and disk- 
ette) that have a relatively small capacity. For example, transferring a 200- 
block file to a DECtape, on which the largest available empty space is 300 
blocks, does not work with a zero-length .ENTER. Since the .ENTER allo- 
cates half the largest space, only 150 blocks are really allocated and an output 
error occurs during the transfer. When transferring from A to B, with the 
length of A unknown, do a .LOOKUP first. This request returns the length so 
that value can be used to do a fixed-length .ENTER. If a specific length of 200 
(or more) is requested, the transfer proceeds without error. The .ENTER 
request generates hard errors when problems are encountered during directory 
operations. These errors can be detected after the operation with the .SERR 
request. 

Errors: 

Code Explanation 

Channel is in use. 

1 In a fixed-length request, no space greater than or equal to m 
was found; or in a nonspecific request, the device or the direc- 
tory was found to be full. 

3 A file by that name already exists and is protected. A new file 
was not opened. 

Example: 

TITLE ENTER. MAC 

+ 
.ENTER - This is an exsmple in the use of the .ENTER reouest . 
The exanple makes a copy of the file 'TECO.SAM' on device DK t 
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.MCALL .LOOKUP, .ENTER, .URITU, . READU, . CLOSE 
.MCALL .PRINT, .EXIT 



start: 



i«: 



2*: 



3$t 



5*: 



6t: 
7$: 



area: 

blk: 

buffr: 

TECO: 



tfile; 



nofil; 

noent: 

uerr; 

rerr; 

done: 



.LOOKUP 

BCS 

hOV 

.ENTER 

BCS 

CLR 

.READU 

BCC 

TSTB 

BEQ 

MOV 

BR 

.WRITW 

INC 

BCC 

MOV 

BR 

.CLOSE 

MOV 

BR 

MOV 

BR 

MOV 

.PRINT 

.EXIT 

• WORD 

.UORIi 

. BLKU 

.RADSO 

.RAD50 

.RADSO 

. RADSO 

. RADSO 

. RADSO 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



♦AREA,*0,*TECO 

5» 

R0,R3 

*ARE6,*1,#TFILE,R3 

6% 

BLK 

♦AREA,*0,*BUFFR,*256, 

2* 

etERRBYT 

3» 

♦RERR.RO 

7« 

♦AREA, *1, ♦BUFFR, 8256. 

BLK 

1* 

*WERR,RO 

7» 

♦ 1 

♦OONE,RO 

7$ 

♦NOFIL, RO 

7$ 

♦NOENT, RO 





0,0,0,0 

256, 

/DK/ 

/TECO/ 

/SAV/ 

/DK/ 

/OLDTEC/ 

/SAV/ 

/?File not found?/ 

/T.ENTER Failed?/ 

/?Urite Error?/ 

/?Re3d Error?/ 

/TECO Copy Complete/ 

START 



SLookup file TECO. SAV 

fBrsnch if not there! 

iCopy size of file to R3 

$Enter 3 new file of ssne size 

jBrsnch if failed 

finitialize block ♦ to zero 
,BLK iResd a block 

SEranch if successful 

!Mas error EOF? 

jBranch if ues 

jHard read error aessaae to RO 

JBrsnch to print wessaae 
,BLK iUrite a block 

iBump block ♦ (doesn't affect C bit) 

jBranch if write was ok 

$R0 => Write error Message 

iBranch to print Message 

JMake new file peraianent 

!R0 => Done message 

(Branch to print aessa^e 

jRO => File not found nessaae 

JBranch to print it 

jRO => Enter Failed nessase 

fPrint nessaae on console terainal 

Jthe exit proaran 

jEMT Ar3u«ent block 

f 

5 1/0 Buffer 

jFile descriptors... 



jMessaae text. 



2.28 .EXIT 



The .EXIT request causes the user program to terminate. When used from a 
background job under the FB monitor or XM monitor, or in SJ, .EXIT causes 
KMON to run in the background area. All outstanding mark time requests 
are canceled. Any I/O reguests and/or completion routines pending for that 
job are allowed to complete. If part of the background job resides where 
KMON and USR are to be read, the user job is written onto the system swap 
blocks (the file SWAP.SYS). KMON and USR are then loaded and control 
goes to KMON in the background area. If RO = when the .EXIT is done, an 
implicit .HRESET is executed when KMON is entered, disabling the subse- 
quent use of REENTER, START, or CLOSE. 

The .EXIT request allows a user program to pass command lines to KMON in 
the chain information area (locations 500-7777[octal]) for execution after the 
job exits. This is performed under the following conditions: 

1. The word (not byte) location 510 must contain the total number of bytes 
of command lines to be passed to KMON. 
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The command lines are stored beginning at location 512. The lines must 
be .ASCIZ strings with no embedded carriage return or line feed. For 
example: 



.=510 

.WORD B-A 

.ASCIZ /COPY A.HAC B.MAC/ 

.ASCIZ /DELETE A.MAC/ 



B: 



3. The user program must set bit 11 in the Job Status Word immediately 
before doing an .EXIT, which must be issued with RO = 0. 

When the .EXIT request is used to pass command lines to KMON, the follow- 
ing restrictions are in effect: 

1. If the feature is used by a program that is invoked through an indirect file, 
the indirect file context is aborted before executing the supplied command 
lines. Any unexecuted lines in the indirect file are never executed. 

2. An indirect file can be invoked, using the steps described above, only if a 
single line containing the indirect file specification is passed to KMON. 
Attempts to pass multiple indirect files or combinations of indirect com- 
mand files and other KMON commands yield incorrect results. An indi- 
rect file must be the last item on a KMON command line. 

The .EXIT request also resets any .CDFN and .QSET calls that were done 
and executes an .UNLOCK if a .LOCK has been done. Thus, the .CLOSE 
command from the keyboard monitor does not operate for programs that 
perform .CDFN requests. 

An attempt to use a .EXIT from a completion routine aborts the running job. 

NOTE 

You must make sure that the data being passed to KMON is 
not destroyed during the .EXIT request. Extreme care should 
be exercised so that the user stack does not overwrite this data 
area. If the user passes command lines to KMON, the stack 
pointer should be reset to lOOO(octal) before an exit is made. 

Macro Call: .EXIT 
Errors: 

None. 
Example: 

.TITLE EXIT. MAC 

+ 

.EXIT - This is. sr; exsmplrf- in the use of the .EXIT reouest. 
The exsuple denonstrates hou 3 conmisnd line iii3>j be passed to 
Keyboard Monitor after Job execution is stopped. 

.MCALL .EXIT 

CHNIF* = 4000 SChain bit in JSU 

JSW = 44 fJSW location 
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start; HOV *510.R0 SRO => Communication area 

MOy tCMIISTRFRl >R1 => Coamand string 

HOy tSTARTfSP SMake sure that the stack is 

rnot in the conniunicat ion ares..> 
10$! iiOV <R1) + .(R0)+ fCopy conmand strind 

CMP R1j*CMDEND JDone? 

BLO 10* iBranch if not 

BIS ♦CHNIF*,e»JSW JSet the "chain" bit to alert KMON that 

fthere's a connand in the communication area 

CLR RO jRO must be zero ! 

.EXIT jExit the proaram 

chdstr: .word cmdend-cmdstr 

.asciz "direct/full *.mac" 
cmdend: 

• EVEN 

•END START 



2.29 .FETCH/.RELEAS 



The .FETCH request loads device handlers into memory from the system 
device. 

Macro Call: .FETCH addr,dnam 

where: 

addr is the address where the device handler is to be loaded 
dnam is the pointer to the Radix-50 device name 

The storage address for the device handler is passed on the stack. When the 
.FETCH is complete, RO points to the first available location above the han- 
dler. If the handler is already in memory, RO contains the same value that was 
initially specified in the argument addr. If the argument on the stack is less 
than 400{octal), it is assumed that a handler .RELEAS is being done. 
(.RELEAS does not dismiss a handler that was LOADed from the KMON; an 
UNLOAD must be done.) After a .RELEAS, a .FETCH must be issued in 
order to use the device again. 

Several requests require a device handler to be in memory for successful 
operation. These include: 

.CLOSE .READC .READ 

.LOOKUP .WRITC .WRITE 

.ENTER .READW .SPFUN 

.RENAME .WRITW .DELETE 

To use device handlers under the XM monitor, load them into memory 
through the keyboard monitor LOAD command. Also, when running under 
the foreground/background monitor, handlers for the foreground program or a 
system job must be loaded with the LOAD command before execution. 

NOTE 

I/O operations cannot be executed on devices unless the han- 
dler for that device is in memory. 
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Errors: 



Code 



Explanation 

The device name specified is not installed in the system, or 
there is no handler for that device in the system. 



Example: 



.TITLE FETCH. MAC 
h 
.FETCH - This is an ex3iiple in the use of the .FETCH reouest. 
The example uses the "specisl" mode of CSI to set sn input 
specification fro* the console terninelj then uses the .BSThTUS 
reQuest to determine if the output device's handler is loadedf 
if not» a .FETCH reauest is issued to load the handler into 
memory. Finally a .DELETE reauest is issued to delete the specified 
file. 



.MCALL .[(STATUS. .PRINT. .EXIT. .FETCH. .CSISPC. .DELETE 



STARTS 


.CSISPC 


*OUTSP.*DEFEXT 




.nSTAT 


*STAT.*OUTSP 




TST 


STAT+4 




BNE 


2$ 




.FETCH 


*HANLOD.*INSPEC 




BCC 


2* 




.PRINT 


♦FEFAIL 




.EXIT 




2t{ 


.DELETE 


*AREA.*0,*INSPEC 




BCC 


3* 




•PRINT 


♦NOFIL 




BR 


START 


3t! 


.PRINT 
.EXIT 


*FILDEL 



area: .blku 2 
stat: .blku 4 
defext; .uord o.o.o.o 



.Use .CSISPC to set output spec 

.Check on the output device 

f (CSISPC catches illegal devices!) 

.See if the device is resident 

(Branch if already loaded 

jIt's not loaded. . .bring it into memora 

.Branch if successful 

iFetch failed. . .print error irtessase 

.then exit proaram 

i Now delete the file 
.Branch if successful 
jF'rint erpor irtesssSe 
jThe tra aSain 

.Acknowledge successful deletion 
.then exit program 

SEMT Argument block 

jBlock for status 

jNo default extensions 



FEFAILS .ASCIZ 
NOFILJ .ASCIZ 
FILDELS .ASCIZ 
.EVEN 



/?. FETCH Failed?/ 
/?File Not FOund?/ 
/IFile Deleted!/ 



jFetch failed messaSe 
.File not found 
(Delete acknoul edsement 
.fix boundary 



OUTSP = . 
INSPEC = .+36 
HANLOD = .+39. 

•END START 



(Output spec Qoes here 

(Input spec is here 

(Handler loaded here <if necessary) 



The .RELEAS request notifies the monitor that a fetched device handler is no 
longer needed. The .RELEAS is ignored if the handler is (1) the system 
device, (2) not currently resident, (3) resident because of a LOAD command 
to the keyboard monitor. .RELEAS from the foreground or system job under 
the FB monitor or from any job under the XM monitor is always ignored, 
since the foreground job in a FB environment and all jobs in an extended 
memory environment can only use handlers that have been loaded by the 
LOAD command. 

Macro Call: .RELEAS dnam 



where: 



dnam is the address of the Radix-50 device name 
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Errors: 

Code Explanation 

Device name is invalid. 
Example: 



.TITLE RELEAB.tlAC 

;iri this example, the DECtape handler (DT) is loaded into iiieMory, 
Mjsed, then released. If the s-stem deuice is DECtape. the handler 
ialways resident, and .FETCH will return HSPftCE in RO. 
.MCALL .FETCH ..RELEAS . .EXIT 



START: 



.FETCH 

BCS 



»HSPACE ,»DTNAME 
FERR 



iLoad DT handler 
i N 1 a u a i 1 a b 1 e 



Use handler 



.RELEAS ftDTNAME 

BR START 
FERR: HALT 
DTNAME: .RAD50 /DT / 
HSPACE: 



I M a r K D T n o 1 o n s e r i v 
j III e III r y 

! D T not available 
SName for DT handler 
! B e S i n n i n S of h a n d 1 e i 
i a r ea 



.END 



START 



2.30 .FORK (Device Handler and Interrupt Service Routine Only) 

The .FORK call is used when access to a shared resource must be serialized or 
when a lengthy but non-time-critical section of code must be executed. 
.FORK issues a subroutine call to the monitor and does not use an EMT 
instruction request. 

Macro call: .FORK fkblk 

where: 

fkblk is a four-word block of memory allocated within the driver 
Errors: 

None. 

The .FORK macro expands as follows: 

.FORK fkblk 
JSR %5,@$FKPTR 
.WORD fkblk-. 

The .FORK call must be preceded by an .INTEN call, and the address of a 
four-word block must be supplied with the request. Your program must not 
have left any information on the stack between the .INTEN and the .FORK 
call. The contents of registers R4 and R5 are preserved through the call, and 
on return registers R0-R3 are available for use. 
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If you are using a .FORK call from a device handler, it is assumed that you 
are also using the other m^acros (.QELDF, .DRBEG, .DRAST, .DRFIN, and 
.DREND) provided for handlers. 

The .DREND macro allocates a word for $FKPTR. This word is filled in at 
bootstrap time for a system device or at LOAD or .FETCH time for a non- 
system device. 

If you want to use the .FORK macro in an in-line interrupt service routine 
rather than in a device handler, you must set up $FKPTR. The recommended 

way v\j KiKJ mio ao cio j.wii^v*ij. 

MOU @#5a,R4 

ADD 402 (R4) »Ra 

HOM R4!$FKPTR 'Bet up pointer 



$FKPTR .WORD 

Once the pointer is set up, use the macro in the usual way as follows: 

.FORK fkblk 

This method permits you to preserve both R4 and R5 across the fork. 

The .FORK request is linked into a queue and serviced on a first-in first-out 
basis. On return to the driver or interrupt service routine following the call, 
the interrupt has been dismissed and the processor is executing at priority 0. 
Therefore, the .FORK request must not be used where it can be reentered 
using the same fork block by another interrupt. It also should not be used with 
devices that have continous interrupts that cannot be disabled. The RT-11 
Software Support Manual gives additional information on the .FORK 
request. 

Notes: 

For use within a user interrupt service routine, monitor fixed offset 402 
(FORK) contains the offset from the start of the resident monitor to the 
.FORK request processor. A .FORK can be done by computing the address of 
the .FORK request processor and using a subroutine instruction. (Under the 
XM monitor, only privileged jobs can contain user interrupt service routines.) 
For example: 

;get base of rmon 
,r4 ;offset to fork processor 
;call fork process 

iFORK BLOCK 

This method destroys the contents of R4. 
Example: 

Refer to the example following the description of .DRAST. 
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MOU 


(1*54 .R4 


ADO 


402 (Rai 


JSR 


R5 .iR4 


.WORD 


BLOCK- . 



2.31 .GMCX (XM Only) 



The .GMCX request returns the mapping status of a specified window. Status 
is returned in the window definition block and can be used in a subsequent 
mapping operation. Since the .CRAW request permits combined window cre- 
ation and mapping operations, entire windows can be changed by modifying 
certain fields of the window definition block. 

The .GMCX request modifies the following fields of the window definition 
block: 

W.N APR base page address register of the window 

W.NBAS window virtual address 

W.NSIZ window size in 32-word blocks 

W.RID region identifier 

If the window whose status is requested is mapped to a region, the .GMCX 
request loads the following additional fields in the window definition block: 

W.NOFF offset value into the region 

W.NLEN length of the mapped window 

W.NSTS state of the WS.MAP bit is set to 1 in the window status 
word. 

Otherwise, these locations are zeroed. 
Macro Call: .GMCX area[,addr] 
where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block where the specified 
window's status is returned 

Request Format: 
RO -► area: 



36 



addr 



Errors: 

Code Explanation 

3 An illegal window identifier was specified. 
Example: 

Refer to the example for the .CRAW request. 
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2.32 .GTIM 



.GTIM allows user programs to access the current time of day. The time is 
returned in two words and given in terms of clock ticks past midnight. 

Macro Call: .GTIM area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the two-word area where the time is to be 
returned 

Request Format: 



RO -+ area: 



21 



addr 



The high-order time is returned in the first word, the low-order time in the 
second word. Your program must account for the conversion from clock ticks 
to hours, minutes, and seconds. 

The basic clock frequency (50 or 60 Hz) can be determined from the configura- 
tion word in the monitor (offset 300 relative to the start of the resident moni- 
tor). In the FB monitor, the time of day is automatically reset after 24:00, 
when a .GTIM request is done and the date is changed if necessary. In the SJ 
monitor, the time of day is not reset. The month is not automatically updated 
in either monitor. (Proper month and year rollover is a special feature that 
you enable through the system generation process.) 

The default clock rate is 60 cycles, that is, 60 ticks per second. Consult the 
RT-11 Installation and System Generation Guide if conversion to a 50-cycle 
rate is necessary. 

Because day rollover is done only through a .GTIM request, make sure that 
your program receives the correct time and day by issuing a .GTIM request 
before using the .DATE request. Nearly all RT-11 system utility programs 
issue a .GTIM request to make sure that rollover occurs daily. If you do not 
use a system utility program regularly, issue a .GTIM request at least once 
during a 24- hour period. 

NOTE 

There are also several SYSLIB routines that perform time con- 
version (see Chapter 3). They are CVTTIM, TIMASC, TIME, 
and SECNDS. 

Errors: 

None. 

Example: 

.TITLE GTIri, HftC 

; + 

i .GTIH - This is an ex3»i>le in the use of the .GTIM reouest. 
r This example is s subroutine that can be assenbled separately 
i ami linked with a user proSraiK 
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calling sequence! 
input; 

OUTPUT! 
ERRORS! 



CALL TIME 

none 

R1 = Minutes in hi bate / hours in lo bate 

R5 = Ticks in hi bate / seconds in lo bate 

(in th3t order for esse of reinovel !> 

none possible 



NOTE! This example cslls SYSLIB functions 'tDIVTK' S 'ffilViO' 





.GLOBL 


tniVTK.iniUAO 




.MCALL 


.GTIM 


TIME!! 


MOV 


*TICKS>R1 




.6TIM 


♦AREA.Rl 




Moy 


(R1)+,R0 




MOV 


gRliRl 




CALL 


ililVTK 




Moy 


R3»R5 




SWAB 


R5 




CALL 


triIV60 




BISB 


R3.R5 




CALL 


$DIV60 




MOV 


R3.R4 




SUAB 


Rl 




BISB 


R1,R4 




RETURN 




AREA! 


• BLKU 


2 


ticks: 


.UORD 


OrO 



jRl points to where to put tine 

JGet ticks since sidnisht vis .GTIM 

iRO = lo order time 

jRl = hi order time 

iCsU SYSLIB 32 bit divide ba elk freo 

iSsve ticks (thea don't bate!) 

fPut them in hi bate 

iCsll SYSLIB divide by 60. routine 

>Put seconds in lo bate 

FDivide ba 60. once sssin 

(Put minutes in R4 

jMove them to hi bate 

jPut hours in lo bate 

iand return 

>EMT argument area 

fTicks since midnight returned here 



■ END 



TIME 



2.33 .GTJB 

The .GTJB request returns information about a job in the system. 

Macro Call: .GTJB area.addrfjobblk] 

where: 

area is the address of a three-word EMT argument block 

addr is the address of an eight- word or twelve-word block into which 
the parameters are passed. The values returned are: 

Word 1 Job Number = priority level *2 (background job is 
0; system jobs are 2, 4, 6, 10, 12, 14; and foreground 
job is 16 in system job monitors; background job is 
and foreground job is 2 in FB and XM monitors; job 
number is in a SJ monitor) 

2 High-memory limit of job partition (last location 
plus 2) 

3 Low-memory limit of job partition (first location) 

4 Pointer to I/O channel space 

5 Address of job's impure area in FB and XM moni- 
tors 

6 Low byte: unit number of job's console terminal 
(used only with multi-terminal option; when 
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multi-terminal feature is not used) 
High byte: reserved for future use 
7 Virtual high limit for a job created with the linker 
A^ option (XM only; when XM monitor or if A^ 
option is not used) 
8-9 Reserved for future use 
10-12 ASCII logical job name (system job monitors only; 
contains zeroes for non-system jobs in FB and XM, 
not defined in SJ) 

juuoiK. IS a poiiiLer iv a uiree-wuru Aot^ii lugicai juu name lur wiiicii 
data is being requested 

Word 4 of addr, which describes where the I/O channel words begin, normally 
indicates an address within the job's impure area. However, when a .CDFN is 
executed, the start of the I/O channel area changes to the user-specified area. 

If the jobblk argument to the .GTJB request is between and 16 when the 
status of a job is requested, it is interpreted as a job number. If the jobblk 
argument is 'ME', or equals -1, information about the current job is returned. 
If the jobblk argument is omitted, or equals -3 (a V03B-compatible parameter 
block), only eight words of information (corresponding to words 1-8 oi addr) 
are returned. 

In an F/B environment without the system job feature, you can get another 
job's status only by specifying its job number (0 or 2). 

Request Format: 



RO ->■ area: 



20 



addr 



jobblk 



Errors: 

Code Explanation 

No such job currently running. 
Example: 

.TITLE GTJB.HAC 

» + 

f .GTJB - This is an e:-:ampie in "the use of the .GTJB reauest. The 
i example Issues the reciuest to determine if there is an active 
» Foresround Job in the system. 



jFind out if FG is active 

SNo active FG Job 

JAnnounce that FG is active 

»Then exit proaram 

JAnnounce that there's no FG Job 

fThen exit proSram 

JEMT Arsuaent block 

SJob parameters passed back here 





.MCALL 


.GTJB. .PRINT. 


START! 


.GTJB 


♦LIST.tJOBARG 




bcs 


1« 




.PRINT 


♦FGACT 




.EXIT 




1$: 


.PRINT 
.EXIT 


*NOFG 


LISTS 


.BLKU 


2 


jobarg: 


.BLKW 


8. 
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fgact; 


.ASCIZ 


/! FG is active 


!/ 


jFG active mess33e 


nofg: 


.ASCIZ 
.EVEN 


/? No FG Job ?/ 




tNo FG message 



.END START 



2.34 .GTLIN 



The .GTLIN request collects a line of input from either the console terminal 
or an indirect command file, if one is active. This request is similar to 
.CSIGEN and .CSISPC in that it requires the USR, but no format checking is 
done on the input line. Normally, .GTLIN collects a line of input from the 
console terminal and returns it in the buffer specified by you. However, if 
there is an indirect command file active, .GTLIN collects the line of input 
from the indirect command file just as though it were coming from the 
terminal. 

When bit 3 of the Job Status word is set, the .GTLIN request collects a line 
from the terminal if there is no line available in the current indirect command 
file. When bit 14 of the Job Status Word is set, the .GTLIN request passes 
lower-case letters. 

An optional prompt string argument (similar to the CSI asterisk) allows your 
program to query for input at the terminal. The prompt string argument is an 
ASCIZ character string in the same format as that used by the .PRINT 
request. If input is from an indirect command file and the SET TT QUIET 
option is in effect, this prompt is suppressed. If SET TT QUIET is not in 
effect, the prompt is printed before the line is collected, regardless of whether 
the input comes from the terminal or an indirect file. The prompt appears 
only once. It is not reissued if an input line is canceled from the terminal by 
CTRL/U or multiple DELETE characters. 

If your program requires a nonstandard command format, such as the user 
identification code (UIC) specification for FILEX, you can use the .GTLIN 
request to accept the command string input line. .GTLIN tracks indirect 
command files and your program can do a pre-pass of the input line to remove 
the nonstandard syntax before passing the edited line to .CSIGEN or 
CSTSPC, 

NOTE 

In an F/B environment, .GTLIN performs a temporary implicit 
unlock while the line is being read from the console. 

Macro Call: .GTLIN linbuf[,prompt] 
where: 

linbuf is the address of the buffer to receive the input line. This area 
must be 81 bytes in length. The input line is stored in this 
area and is terminated with a zero byte instead of (ret) © 
(octal 15 and 12) 
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prompt is an optional argument and is the address of a prompt string 
to be printed on the console terminal. The prompt string has 
the same format as the argument of a .PRINT request. Usu- 
ally, the prompt string ends with an octal 200 byte to sup- 
press printing the carriage returnAine feed at the end of the 
prompt 

NOTE 

The only requests that can take their input from an indirect 
command file are .CSIGEN, .CSISPC, and .GTLIN. The 

T'T'VT'M ^-^A TTTINJT? T-orincsa+a r^artrinf orpf pVinrnrfpr« frOTTl RTi 

indirect command file. They get their input from the console 
terminal (or from a BATCH file if BATCH is running). The 
.TTYIN and .TTINR requests are useful for information that is 
dynamic in nature — for example, when all files with a .MAC 
file type need to be deleted or when a disk needs to be initial- 
ized. In these circumstances, the response to a system query is 
usually collected through a .TTYIN so that confirmation can 
be done interactively, even though the process may have been 
invoked through an indirect command file. However, the re- 
sponse to the linker's Transfer Symbol? query would normally 
be collected through a .GTLIN, so that the LINK command 
could be invoked and the start address specified from an indi- 
rect file. Also, if there is no active indirect command file, 
.GTLIN simply collects an input line from the console terminal 
by using .TTYIN requests. 

Errors: 

None. 
Example: 

.TITLE GTLIN. MAC 
t X 

i .GTLIN - This is an example in the use of the .GTLIN reouest. 
5 The example merela acepts input from the console terminal and 
t echoes it back. 



.HCALL .6TLIN».PRINT».EXIT 



START! 


.GTLIN 


»BUFF,*PROMT 




TSTB 


BUFF 




BEQ 


1* 




.PRINT 


♦ BUFF 




CLRB 


BUFF 




BR 


START 


1$J 


.EXIT 




buff: 


.BLKU 


41. 


PROMT! 


.ASCII 


/Enter somet 




.END 


START 



jGet a line of input from keyboard 
SNothina entered? 
fBranch if nothing entered 
SEcho the input back 
iClear first char of buffer 
fGo hack for more 
jExit proaram on null input 
iSO character buffer (ASCIZ for .PRINT) 
somethina/<12><15>/>/<200> 



2.35 .eVAL 



The .GVAL request returns a monitor offset value in RO. This request must be 
used in an XM monitor environment to access the monitor's fixed offset 
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locations. It should also be used in other RT-11 monitors. The .GVAL request 
is a read-only operation and protects the information obtained from the moni- 
tor. A table of the fixed offset locations can be found in Chapter 2 of the 
RT-11 Software Support Manual. 

Macro Call: .GVAL area,offse 

where: 

area is the address of a two-word EMT argument block 

offse is the displacement from the beginning of the monitor to the 
word to be returned to RO 



Request Format: 
RO -► area: 



34 



offset 



Errors: 



Code 





Explanation 

The offset requested is beyond the limits of the resident 
monitor. 



Example: 



.TITLE GVAL. MAC 



; + 



> .GVAL - This is sn exsBPle in the use of the .GVAL reaoest. The 
5 example is sn slternstive nethod of finding out whether the FG 
i is 3ctive to the nethod shown in the .GTJB exanple. 





.HCALL 


.GVAL. .PRINT. .EXIT 




CONFIG 


= 300 




FJDB$ 


= 200 


START! 


.GVAL 


*AREA.*CONFIG 




BIT 


#FJOB»,RO 




BEQ 


1» 




.PRINT 


♦FGACT 




.EXIT 




1*: 


.PRINT 
.EXIT 


tNOFG 


area; 


.BLKU 


2 


FGACT! 


.ASCIZ 


/! FG is active !/ 


NOFG! 


.ASCIZ 
.EVEN 


/? No FG Job ?/ 



JOffset in Monitor of Configuration 

.word 

.Bit in Confia Uord is on if FG active 

JGet Monitor CONFIG word in RO 
!See if FG Active bit is on 
.Branch if not 
{Announce FG is active 
ithen exit prosrain 
SAnnounce there's no FG Job 
ithen exit proSram 

jEMT Argument block 
jFG active message 
iNo FG message 
.Fix boundapa 



.END 



START 



2.36 .HERR/.SERR 



.HERR and .SERR are complementary requests used to govern monitor be- 
havior for serious error conditions. During program execution, certain error 
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conditions can arise that cause the executing program to be aborted (see 
Table 2-2). 

Normally, these errors cause program termination with one of the ?MON- 
error messages. However, in certain cases it is not feasible to abort the pro- 
gram because of these errors. For example, a multi-user program must be able 
to retain control and merely abort the user who generated the error. .SERR 
accomplishes this by inhibiting the monitor from aborting the job and causing 
an error return to the offending EMT. On return from that request, the carry 
bit is set and byte 52 contains a negative value indicating the error condition 



T /-Vi^TrTTT* 



that occurred, in some cases (sucii as tiie .L,uui\ur ana .ENTER requesLs;, 
the .SERR request leaves channels open. It is your responsibihty to perform 
.PURGE or .CLOSE requests for these channels, otherwise subsequent 
.LOOKUP/.ENTER requests will fail. 

.HERR turns off user error interception. It allows the system to abort the job 
on fatal errors and generate an error message. (.HERR is the default case.) 



Macro Calls: 



.HERR 
.SERR 



Request Formats: 



.HERR Request RO = 
.SERR Request RO = 



5 





4 






Errors: 

Table 2-2 contains a list of the errors that are returned if soft error 
recovery is in effect. Traps to locations 4 and 10, and floating-point 
exception traps are not inhibited. These errors have their own recovery 
mechanism. 

Table 2-2: Soft Error Codes (.SERR) 



Code 



-1 
-2 
-3 
-4 

-5 
-6 



-10 
-11 



Explanation 



Called USR from completion routine. 

No device handler; this operation needs one. 

Error doing directory I/O. 

.FETCH error. Either an I/O error occurred while the handler was being used, or an 
attempt was made to load the handler over USR or RMON. 

Error reading an overlay. 

No more room for files in the directory. 

Illegal address (FB only); tried to perform a monitor operation outside the job 
partition. 

Illegal channel number; number is greater than actual number of channels thai 
exist. 

Illegal EMT; an illegal function code has been decoded. 
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Example: 



.TITLE HERR.MAC 
h 
.HERR / .SERR - This is an example in the use of the .HERR S .SERR 
reouests. Nori»3lly fatal errors will cause a return to the user 
proaram for processing and printing of an appropriate error nessa^E 



•MCALL .HERR. .SERR. .LOOKUP. .PURGE 
.hCALL .EXIT. .PRINT. .CSISPC 



start: 



.Let proSram handle fatal errors 
fUse .CSISPC to aet filespec 



error: 



ftlerr: 



.SERR 

.CSISPC *OUTSP.»DEFEXT 

.PURGE »0 

»AREA.*0.»0UTSP+36 

ERROR .Branch if there was an error 

.Now permit '?MON-F-' errors. 
♦LUPOK .Announce successful LOOKUP 

.Exit prosran 
fuas the error fatal? 
^Branch if aes 



8*52. RO 

FTLERR 

♦NOFIL 



RO 
RO 
RO 
TBL(RO).RO 

START 



.Try aSain. . . 

jMake error ♦ positive 

i Adjust bu one 

(Multiply ba 2 to make an index 

.Put nessa^e address into RO 

.and print it. 

.Go tra sone more errors 

.Table of Error Message Addresses 



.LOOKUP 

BCS 

.HERR 

.PRINT 

.EXIT 

MOVE 

BMI 

.PRINT 

BR START 

NEC 

DEC 

ASL 

NOV 

.PRINT 

BR 

tbl: Ml 

M2 

M3 

H4 

M5 

H6 

MV 

MIO 

Mil 

iError MessaSes... 
Ml* .Not possible in this prodram 

M2: .ASCIZ /Tllleaal Device -or- No Handler?/ 
M3: .ASCIZ /?Director« I-O Error?/ 

^^* 'Not possible in this proSran 

•^5: .Not possible in this proSram 

^^* .Not possible in this prosran 

M7: .ASCIZ /TAddress Check Error?/ 
MlO: .ASCIZ /?IlleS3l Channel?/ 
Mil: .ASCIZ /?IlleS3l EMT?/ 
NOFILJ .ASCIZ /?File Not Found?/ 
LUPOK: .ASCIZ /Lookup suceeed<=ri/ 

.EVEN .Fix boundary 

area: .BLKW 4 JEMT ArSunent block 

DEFEXT: .UORD O.O.O.O SNo default extensions 

OUTSP = , .Output spec Soes here 

HANLOD = . + 36 .Handlers Loaded here 



.END 



START 



2.37 .HRESET 



The .HRESET request stops all I/O transfers in progress for the issuing job, 
and then performs an .SRESET request. (.HRESET is not used to clear a 
hard-error condition.) In an SJ environment, a hardware RESET instruction 
is used to terminate I/O. In an FB or XM environment, only the I/O associ- 
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ated with the job that issued the .HRESET is affected by entering active 
handlers at the abort entry point of the handler. All other transfers continue. 

Macro Call: .HRESET 

Errors: 

None. 
Example: 

Refer to the example for .SRESET for format. 



2.38 .INTEN 

.INTEN is used by interrupt service routines to: 

1. Notify the monitor that an interrupt has occurred and to switch to system 
state. 

2. Set the processor priority to the correct value. 

3. Save the contents of R4 and R5 before returning to the Interrupt Service 
Routine. Any other registers must be saved by you. 

.INTEN issues a subroutine call to the monitor and does not use an EMT 
instruction request. 

All external interrupts must cause the processor to go to priority level 7. 
.INTEN is used to lower the priority to the value at which the device should 
be run. On return from .INTEN, the device interrupt can be serviced, at 
which point the interrupt routine returns with an RTS PC. 

NOTE 

An RTI instruction does not return correctly from an interrupt 
routine that specifies an .INTEN. 

Macro Call: .INTEN prio[,pic] 

where: 

prio is the processor priority at which to run the interrupt routine, 
normally the priority at which the device requests an interrupt 

pic is an optional argument that should be non-blank if the interrupt 
routine is written as a PIC (position-independent code) routine. 
Any interrupt routine written as a device handler must be a PIC 
routine and must specify this argument 

Errors: 

None. 
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Example: 



.TITLE SLll.MAC 



SLll.MAC - This is an estainple in the use of the .INTEN reauest. 
The exsnple is an in-line, interrupt service routine, which may 
be Bssenbled separately and linked with 3 mainline proaram. 
The routine transfers data from 3 user specified buffer to 3 DLll 
Serial Line Interface. 



CALLING FORMAT! 







BUFFER! .BLKW 




.MCALL 


.INTEN 


DLVEC 


= 304 




DLCSR 


= 176504 


DLPRI 


= 4 




SLll! : 


hoy 


(R5)+,(PC)+ 


UCNT! 


.WORD 







HOV 


<R5)+, (PC)+ 


bufad: 


.UORIi 







ASL 


WCNT 




BEQ 


1» 




MOV 


♦DLINTretDLVEC 




BIS 


*100,e*DLCSR 


1*; 


RETURN 




dlint: 


.INTEN 


DLPRI 




MOMB 


eBUFAD,e*DLCSR+2 




INC 


BUFAD 




DEC 


UCNT 




BEQ 


DLDUN 




RETURN 




dldun: 


BIC 
RETURN 


»100,e*DLCSR 




.END 


SLll 



JSR R5.SL11 
.WORD wordcount 
.WORD BUFFER 



wordcount 



i Initiate Output 

it words to transfer 

jAddress of Data Buffer 



JDLll Vector *«* 
iDLll Output CSR **« 
>DL11 Priority for RT-11 

JI/0 Initiation - Get word count 

SGet address of Data Buffer 

fMske word count byte count 
jJust leave if zero word count 
JInitialize DLll interrupt vector 
JEnable interrupts 
jReturn to caller 

finterrupt service - Notify RT-11 

fand drop priority to that of DLll 

jTransfer a byte 

iBump buffer pointer 

jAll bytes transfered? 

JBranch if yes 

jNo return from interrupt thru RT-11 

JAll done - disable DLll interrupts 
iReturn thru RT-11 



2.39 .LOCK/.UNLOCK 



.LOCK 

The .LOCK request keeps the USR in memory to provide any of its services 
required by your program. If all the conditions that cause swapping are satis- 
fied, the part of the user program over which the USR swaps is written into 
the system swap blocks (the file SWAP.SYS) and the USR is loaded. Other- 
wise, the copy of the USR in memory is used, and no swapping occurs. (Note 
that certain calls always require a fresh copy of the USR.) A .LOCK request 
always causes the USR to be loaded in memory if it is not already in memory. 
The USR is not released until an .UNLOCK request is given. (Note that 
under an FB monitor, calling the CSI can also perform an implicit and 
temporary .UNLOCK.) A program that has many USR requests to make can 
.LOCK the USR in memory, make all the requests, and then .UNLOCK the 
USR. 

In a FB environment, a .LOCK inhibits the other job from using the USR. 
Note that the .LOCK request reduces time spent in file handling by eliminat- 
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ing the swapping of the USR in and out of memory. .LOCK causes the USR to 
be read into memory or swapped into memory. After a .LOCK has been 
executed, an .UNLOCK request must be executed to release the USR from 
memory. The .LOCK/.UNLOCK requests are complementary and must be 
matched. That is, if three .LOCK requests are issued, at least three 
.UNLOCK requests must be done, otherwise the USR is not released. More 
.UNLOCK than .LOCK requests can be issued without error. 

Macro Call: .LOCK 

Notes: 

1. It is vital that the .LOCK call not come from within the area into which 
the USR will be swapped. If this should occur, the return from the .LOCK 
request would not be to the user program, but to the USR itself, since the 
.LOCK function inhibits the user program from being re-read. Also, none 
of the executable code should be in the area that the USR will occupy 
while it is locked. 

2. Once a .LOCK has been performed, it is not advisable for the program to 
destroy the area the USR is in, even if no further use of the USR is 
required, because this causes unpredictable results when an .UNLOCK is 
done. 

3. If a foreground job performs a .LOCK request while the background job 
owns the USR, foreground execution is suspended until the USR is avail- 
able. In this case, it is possible for the background to lock out the fore- 
ground (see the .TLOCK request). 

Errors: 

None. 
Example: 

Refer to the example for the .UNLOCK request. 

.UNLOCK 

The .UNLOCK request releases the User Service Routine (USR) from mem- 
ory if it was placed there with a .LOCK request. If the .LOCK required a 
swap, the .UNLOCK loads the user program back into memory. There is a 
.LOCK count. Each time the user does a .LOCK, the lock count is incre- 
mented. When the user does an .UNLOCK, the lock count is decremented. 
When the lock count goes to 0, the user program is swapped back in (see 
note 1). 

Macro Call: .UNLOCK 
Notes: 

.LOCK requests that were issued. If more .LOCK requests are done, the 
USR remains locked in memory. Extra .UNLOCK requests in your pro- 
gram do no harm since they are ignored. 
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2. With two running jobs in an FB environment use .LOCK/.UNLOCK pairs 
only where absolutely necessary. When a job locks the USR, the other 
job cannot use it until it is unlocked, which can degrade performance in 
some cases. 

3. In an FB environment, calling the CSI with input coming from the console 
terminal results in an implicit (though temporary) .UNLOCK. 

4. Make sure that the .UNLOCK request is not in the area that the USR 
swaps into. Otherwise, the request can never be executed. 



Errors: 



None. 



Example: 



.TITLE LOCK. MAC 



.LOCK / .UNLOCK - This is an example in the use of the .LOCK 3nd .UNLOCK 
reauests. This example tries to obtain as much nenoru as possible <usinS 
the .SETTOP reouest)i which will force the USR into a suappins mode. The 
.LOCK reouest will brinS the USR into memoru (over the hish 2k of our littls 
proSram !) and force it to remain there until an .UNLOCK is issued. 



start: 

2$: 

i«: 



.MCALL 
.MCALL 



•LDCKf .UNLOCKj .LOOKUP 
.SETTOPi .PRINTj.EXIT 



SYSPTR=54 

.SETTOP e*SYSPTR 

.LOCK 

.LOOKUP *AREAf*0>*FILEl 



BCC 

.PRINT 

.EXIT 

.PRINT 

MOV 

INC 

MOV 

•LOOKUP 



1* 
*LMSG 

♦FIFND 
»AREArRO 
0RO 
»FILE2»2<R0) 



BCS 2* 
.PRINT *F2FNIr 
.UNLOCK 
.EXIT 



jPointer to beginning of RMON 

fTra to allocate all of memoru (up to RMON) 

rbrins USR into memory 

f LOOKUP a file on channel 

jBranch if successful 

JPrint Error Message 

fthen exit proarsm 

rAnnounce our success 

fRO => EMT Argument Block 

(Increment low b«te of 1st ara (chan *) 

jFill in pointer to new filespec 

fDo the .LOOKUP from filled in arS block 

Jpointed to b« RO. 

jBranch on error 

iSau we found it 

rnow release the USR 

Sand exit program 



area: 

FILci 5 



FILE2; 



lhsg: 
fifnd: 

F2FND: 



.blku 

.RhDSC 

.RAD50 

.RAII50 

.RAD50 

.RAD50 

.RAD50 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.END 



3 

/ D K / 

/PIP / 

/SAV/ 

/DK/ 

/TECO / 

/SAV/ 

/TError on .LOOKUP?/ 

/. . .Found PIP. SAV/ 

/,. .Found TECO. SAV/ 

START 



fEMT Argument Block 



JM r.i.Jbtr we 



SAnother file we mi^ht find 



fError message 



2.40 .LOOKUP 



A .LOOKUP request can be used in two different ways. The first way is to use 
the request as a standard lookup, which occurs under the SJ, FB, and XM 
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monitors. The second way is to use the request when the system job feature is 
implemented. Both ways are described in this section. 

2.40.1 Standard Lookup 

The .LOOKUP request associates a specified channel with a device and exist- 
ing file for the purpose of performing I/O operations. The channel used is then 
busy until one of the following requests is executed: 

.CLOSE 

.SAVESTA'l'Uy 

.SRESET 

.HRESET 

.PURGE 

.CSIGEN (if the channel is in the range 0-10 octal) 

Note that if the program is overlaid, channel 17 (octal) is used by the overlay 
handler and should not be modified. 

If the first word of the file name (the second word of dblk) is and the device 
is a file-structured device, absolute block of the device is designated as the 
beginning of the file. This technique is called a non-file-structured .LOOKUP 
and allows I/O operations to access any physical block on the device. If a file 
name is specified for a device that is not file structured (such as 
PC:FILE.TYP), the name is ignored. 

The handler for the selected device must be in memory for a .LOOKUP. On 
return from the .LOOKUP, RO contains the length in blocks of the file just 
opened. On a return from a .LOOKUP for a non-directory, file-structured 
device, RO contains for the length. 

NOTE 

Care should be exercised when doing a non-fiie-structured 
.LOOKUP on a file-structured device, since if your program 
writes data, corruption of the device directory can occur and 
effectively destroy the disk. (The RT-11 directory starts in ab- 
solute block 6.) 

In particular, avoid doing a .LOOKUT or .ENTER with a file 
specification where the file value is missing. If the device type 
is not known in advance and is to be entered from the key- 
board, include a dummy file name with the .LOOKUP or 
.ENTER, even when it is assumed that the device is always 
non-file structured. 

Macro Call: .LOOKUP area,chan,dblk[,seqnum] 

where: 

area is the address of a three-word EMT argument block 

chan is a channel number in the range 0-377(octal) 
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-1 



dblk is the address of a four-word Radix-50 descriptor of the file to 

be operated upon 

seqnum is a file number for magtape and cassette. 

For cassette operations, if this argument is blank, a value of 
is assumed. 

For magtape, it describes a file sequence number. The action 
taken depends on whether the file name is given or is null. 
The sequence number can have the following values: 

means suppress rewind and search for a file name from 
the current tape position. If a file name is given, a file- 
structured lookup is performed (do not rewind). It is im- 
portant that only -1 be specified and not any other num- 
ber. If the file name is null, a non-file-structured lookup 
is done (tape is not moved). 

means rewind to the beginning of the tape and do a non- 
file-structured lookup. 

where n is any positive number. This means position the 
tape at file sequence number n and check that the file 
names match. If the file names do not match, an error is 
generated. If the file name is null, a file-structured 
lookup is done on the file designated by seqnurn. 



Request Format: 
RO -► area: 



chan 



dblk 



seqnum 



Errors: 



Code 



Explanation 



Channel already open. 

1 File indicated was not found on the device. 
Example: 

•TITLE LOOKUP. MAC 

1 + 

i .LOOKUP - This is an examr-le in the use of the .LOOKUP reauest. 
> This exaaple deteraines whether or not the RT-U Device Queue 
» Uorkfile exists on device DK; and if sof prints its size in 
i blocks on the console terainel. 
t- 



•MCALL .LOOKUPf.PRINTr.EXIT 

start: .LOOKUP *AREA>*Or*QUSPEC 

BCC 1* 

.PRINT tNOFIL 

.EXIT 

1*: HOV tSlZb>Kl 

CALL CNUIO 

.PRINT ♦BUFF 

.EXIT 



I'See if there's 3 DKtQUFILE.TMP 

jBrsnch if there is 

jPrint 'File Not Found' aesss^e 

ithen exit prodraa 

(Rl => where to Put ASCII size 

•Convert size (in RO) to ASCII 

JPrint size of QUFILE.TMP on console 

rthen exit proaraa 
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CNUio: 


HOV 


ROf-<SP) 




fSubroutine to convert Binary * in RO 




CLR 


RO 




;to DeciJial ASCII bu repetitive 


i«i 


IMC 


RO 




isubtrsetion. The reaainder for each 




SUB 


*io.>esp 




$ radix is Bade into ASCII and pushed 




BGE 


1* 




fon the stacks then the routine calls 




ADD 


•72i0SP 




Utself. The code at 2* pops the ASCII 




DEC 


RO 




Idisits of the stack and into the out- 




BEQ 


2« 




rput bufferr eventually returninn to 




CALL 


CNVIO 




>the calling proaraa. This is a MERY 


2«: 


HOVB 
RETURN 


(SP)+f<Rl)+ 




ruseful routinef is short and is 
raeaoru effecient. 


AREAi 


.BLKU 


3 




SEMT Arauaent Block 


QUSPEC: 


.RAD50 
.RAD50 


/DK QUFILE/ 
/THP/ 






BUFF 5 


.ASCII 


/dk:qufile.tmp = 


/ 




size: 


.ASCIZ 


/ Sioeks/ 






nofil: 


.ASCIZ 
.EVEN 


/?File Not Found 


DK 


QUFILE. TMP ?/ 



.END 



START 



2.40.2 System Job Lookup 

The foreground and background jobs can send messages to each other via the 
existing .SDAT/.RCVD/.MWAIT facility. A more general message facihty is 
available to all jobs through the message queue (MQ) handler. By turning 
message handling into a formal "device" handler, and treating messages as 
I/O to jobs, the existing .READ/CAV-.WRITE/C/W-.WAIT mechanism can 
be used to transmit messages. A channel is opened to a job via a .LOOKUP 
request, after which standard I/O requests are issued to that channel. 

Macro Call: .LOOKUP area,chan,jobdes 
where: 



area 

chan 

iobdes 



is the address of a three-word EMT argument block 

is the number of the channel to open 

is the address of a four-word descrintor of the iob to which 
messages will be sent or received 

jobdes -* .RAD50 /MQ/ 

.ASCII /logical-job-name/ 

where logical-job-name can be from one to six characters long. 
It must be padded with zeroes if less than six characters long. 
If logical-job-name is zero, the channel will be opened for 
.READ/C/W requests only and such requests will accept mes- 
sages from any job 

Request Format: 
RO 



area: 



1 



chan 



jobdes 



seqnum 



The .LOOKUP request associates a channel with a specified job for the pur- 
poses of sending inter-task messages. RO is undefined on return from the 
.LOOKUP. 
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Errors: 



Code Explanation 

Channel already open. 

1 No such job. 
Example: 

•TITLE SJLOOK.MAC 



.LOOKUP - This is an e:;3Bple in the use of the .LOOKUP reouest 
to open a messsse channel to 3 Sastem Jobp specif icsllyj the 
RT-11 Device Queue Foreground proSran. NOTE! This enaitiple assumes 
it will be run under an FB Honitor Generated with System Job 
Support and that QUEUE. REL has been successfully FRUN/SRUN !!! 



.MCALL .LOOKUPr .PRINTr .EXITj .URITU. .READU 



start: .lookup tAREAitOrtQhSG 



If: 



area: 
qhsg: 



rhsg: 

hsgerr; 
NO job: 

QRUN! 



BCC 

.PRINT 

.EXIT 

.WRITU 

BCS 

.READU 

BCS 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.BLKU 

.RAD50 

.ASCIZ 

.UORD 

.WORD 

.ASCII 

, ASCIZ 

.ASCIZ 

.ASCIZ 

.EMEN 

.END 



1* 
tNOJOB 

*AREA>t0f*RMSGr*6 

2« 

*AREA>t0rtRHSGp*6 

2* 

tQRUN 

tMSGERR 



I Try to open a channel to QUEUE 

fBranch if successful 

JError .. .print error message 

J then exit proaram 

rSend 3 meaningless message to QUEUE 

jBranch if error 

rWait for an acknowledgement message 

(Branch if error 

(Announce QUEUE alive and well 

(Then eiiit 

(Print error message 

(Then exit 



5 

/MQ/ 

/QUEUE/ 

OiO 



/SJLOOK/ 

/?Mess3ge Error?/ 

/TDUEUE is not running?/ 

/! QUEUE is alive and running 

START 



(EMT Argument Block 

(Job Descriptor Block for .LOOKUP 



(Dummy message. 



(Error Messasesj etc. 



!/ 



2.41 .MAP (XM Only) 



The .MAP request maps a previously defined address window into a dynamic 
region of extended memory or into the static region in the lower 28K words of 
memory. If the window is already mapped to another region, an implicit 
unmapping operation is performed (see the .UNMAP programmed request). 

Macro Call: .MAP area[,addr] 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the window definition block containing a de- 
scription of the window to be mapped and the region to which it 
will map. 
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Request Format: 
RO -> area: 

Errors: 



36 



addr 



Code Explanation 

2 An invalid region identifier was specified. 

3 An invalid window identifier was specified. 

4 The specified window was not mapped because the offset is 
beyond the end of the region, the region is larger than the win- 
dow, or the window would extend beyond the bounds of the 
region. 

Example: 

Refer to example for the .CRAW request. 



2.42 .MFPS/.MTPS 



The .MFPS and .MTPS macro calls allow processor-independent user access 
to the processor status word. The contents of RO are preserved across either 
call. 

The .MFPS call is used to read the priority bits only. Condition codes are 
destroyed during the call and must be directly accessed (using conditional 
branch instructions) if they are to be read in a processor-independent manner. 

In the XM monitor, .MFPS and .MTPS can be used only by privileged jobs 
and are not available for use by virtual jobs. 

Macro Call: .MFPS addr 
where: 

addr is the address into which the processor status is to be stored; if 
addr is not present, the value is returned on the stack. Note that 
only the priority bits are significant 

The .MTPS call is used to set the priority condition codes and to trace the 
trap bit with the value designated in the call. 

Macro Call: .MTPS addr 
where: 

*jf^\jLi. xB cxi^ cc^ct.xV'Oo v/x i^xxC vv^xVA ij\j PL/C j^ici*.^c:ix ill uiic; jjJlv^vCOOMi kSLOli'Ll.O 

word. If addr is not present, the processor status word is taken 
from the stack. Note that the high byte on the stack is set to 
when maryaddr is present. If addr is not present, you should set 
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the stack to the appropriate value. In either case, the lower byte 
on the stack is put in the processor status word 



Note: 



It is possible to perform MTPS and MFPS operations and access the condi- 
tion codes by following this special technique: 

1. In the beginning of your program, set up the lOT trap vector as 
follows: 

♦ASECT ;SET UP lOT 

. = 20 

.WORD GETPS ;iOT SERVICE ADDRESS IN 'MFPS' SUBROUTINE 

.WORD 3ilO i PRIORITY 7 

2. Elsewhere in your program place the following routines: 



MFPS/MTPS ROUTINES 



MFPS: lOT iEXECUTE IDT 

;WILL RETURN TO CALLER W/ PS ON STACK 

GETPS: MOU a(SP) .®SP iPUT USER RETURN ON TOP 

MOM 2(SP) .4(SP) iMOME PS SAVED BY lOT 
MTPS: RTI iWILL RETURN TO CALLER W/ NEW PS 

3. To get the PS or to set the PS to a desired value, follow this sequence 
of instructions: 

; + 

; TO GET PS . . . 



JSR PC, MFPS ;get PS 

;CONTINUE, PS IS ON STACK . 



+ 
TO PUT PS , . , 



MOM NEWPS,-(SP) ;PUT DESIRED PS ON STACK ... 
JSR PC ,MTPS ;CALL MTSP 

;CONTINUE PROCESS W/ NEW PB . 

Errors: 

None. 
Example: 

.TITLE MFPS 

; + 

i .HFPS / .MTPS - This is an exsBPle in the use of the .MFPS and .MTPS 
I reauests. The eKaBiple is a skeleton mainline proSrsm which calls a 
I subroutine to ii&t the fie>; t Trtfe elt^intnt in oii nliii Air. g iirir-. Bu GUBUS. 

9 ~ 

•MCALL .MFPSf .MTPSf.EXITf .PRINT >. TTINR 
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JSW = 44 
TTSPC* = 10000 



JJob Status Word location 
STTY Special bit 



start: 



BIS 



*TTSPC*>e*JSU 



fSkeleton mainline proSran. 
iSet TTY Special bit 



CALL 



GETQUE 





BCC 


1» 




.print 


♦NOELEM 




BIC 


♦TTSPCt»e*JSU 




.exit 




i»: 


NOP 






.PRINT 


♦GOTl 


2»{ 


.TTINR 






BCS 


2* 




BR 


START 


getque; 


MOV 


«QHEAD>R4 




TST 


eR4 




BEQ 


11* 




.MFPS 






.MTPS 


♦ 340 




hOV 


eR4.R5 




MOV 


eR5.eR4 




.MTPS 






TST 


(PC) + 


11*5 


SEC 
RETURN 





SCall subroutine to return next free 

felenent - on return R5 => element 

fBranch if no error 

jNo nore elements available 

jReset special bit 

jExit proaram 

JProaram continues 

jAnncounce success 

JWait for a keu to be hit on console 



JPoint to Queue head 

i Queue exhausted? 

JYes.i.set error on leavins 

jSave status on stack 

fRaise priorit« to 7 

fR5 points to next element 

iRelink the Queue 

.'Restore previous status 

iThis clears carry X skips next instruction 

(Set carra bit (to fl32 error) 

iReturn to caller 



QHEADt .WORD Ql 

QIJ .WORD Q2!0f0 

Q2; .UORD Q3i0f0 

Q3: .UORD 0»0.0 



jQueue head 

53 linked aueue elements 



NOELEM: .ASCIZ /?No more Queue Elements Available?/ 

GOTlt .ASCIZ /Element scnui red. ,. press arm key to continue/ 

.END START 



2.43 .MRKT (FB and XM : SJ Monitor Special Feature) 

The .MRKT request schedules a completion routine to be entered after a 
specified time interval (measured in clock ticks) has elapsed. The .MRKT 
request is an optional feature in the SJ monitor, and is selected as a system 
generation option. 

A .MRKT request requires a queue element taken from the same list as the 
I/O queue elements. The element is in use until either the completion routine 
is entered or a cancel mark tim.e request is issued (see .CMKT request). The 
user should allocate enough queue elements to handle at least as many mark 
time and I/O requests that are expected to be pending simultaneously. 

Macro Call: .MRKT area,time,crtn,id 



where: 



area is the address of a four-word EMT argument block 

time is the address of a two word-block containing the time interval 
(high order first, low order second), specified as a number of 
clock ticks 
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crtn is the entry point of a completion routine 

id is a non-zero number or memory address assigned by the user to 

identify the particular request to the completion routine and to 
any cancel mark time requests. The number must not be within 
the range 177400-177777, which is reserved for system use. The 
number need not be unique (several .MRKT requests can spec- 
ify the same id). On entry to the completion routine, the id 
number is in RO 



Request Format: 
RO -► area: 



22 





time 


crtn 


id 



Errors: 



Code 



Explanation 



No queue element was available. 



Example: 



.TITLE TREAD. MAC 
> + 

i .MRKT/.CMKT - This is sn e>;s»iple in the use of the .MRKT/.CMKT reouests 
i The example illustrates 3 user i sf lemented "Timeci Read" to cancel an 
J input renuest after a specified time interval. 
5 - 

MRKT, . TTINR r .EXIT, , PRINT ,. TTYOUT , ,CMKT, .TUAIT, .QSET 

rLine Feed 

jJob Status Word location 
fReturn C-hit bit in JSU 
jTTY Special Mode bit in JSU 

JNeed an extra Q-Elem for this 

fMainline - RO => ProBpt 

fRl => Input buffer 

jDo a "timed read" 

;C-bit set = Timed out 

i "Process" data. , . 

fGo back for more 

jRead timed out - could process 

fpartial data but we'll Just exit 

r* TREAD* - "Timed Read" Subroutine « 

i* Input; RO => Prompt StrinS / RO = if no prompt * 

j* Rl => Input Buffer « 

j« Outputs Buffer contains input chars, if anu, terminated « 

'* bH a null char. C-Bit set if timed out $i 





.MCALL 


.MRKT,.TT 




LF = 12 






JSU = 44 




TCBIT* 


= 100 




TTSPC* 


= 10000 


START! 


.QSET 


tXQUE,*l 


1$: 


MOM 


♦PROMT, RO 




MOV 


*BUFFR,R1 




CALL 


TREAD* 




BCS 


2* 




.PRINT 


*LINE 




BR 


1* 


2$; 


.PRINT 
.EXIT 


♦TIMOUT 



TREAD* 


! TST 


RO 




BEQ 


1* 




.PRINT 




1*: 


CLR 


TBYT 




.MRKT 


*TAREA,*TIME,*T0UT,#1 




BIS 


♦TCBIT*, e*JS« 




CLRB 


eRi 


ttin: 


.TUAIT 
.TTINR 


♦ AREA 




BIT 


♦1,(PC)+ 


TBYT5 


.UORD 







BNE 


2* 




BCS 


TTIN 



JSee if we have to prompt 

jBranch if no. . . 

JOutput prompt 

(Clear time-out flas 

jlssue a .MRKT for 10 sec 

jSet C-Eit bit in JSU (for F/B) 

JStart with "empta" buffer 

iUait so we don't lock out BG 

$Look for a character 

fTimed out? 

5Time-out flas 

JBranch if ues 

fBranch if input not complete 
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MQVB 


ROr(Rl)+ 




.CMKT 


*TAREA»*0 


2$: 


BIS 


♦TTSPC».e*JSW 


3*1 


.TTINR 






MOMB 


R0.<R1)+ 




BCC 


3* 




CLRB 


-(Rl) 




BIC 


*TCBIT*!TTSPC«Fe*JSU 




ROR 


TBYT 




RETURN 




TOUT! 


INC 
RETURN 


TBYT 


XQUE5 


.BLKU 


10. 


area: 


.UORD 


OjUAIT 


tarea; 


.BLKW 


4 


time; 


.UORD 


Oii&OO. 


wait: 


.UORD 


0»1 


line: 


.ASCII 


/Not in stock - Psrt * 


BUFFRJ 


.BLKB 


81. 


PROMT! 


.ASCIZ 


/Enter Part « >/<200> 


TIMOUT! 


.ASCIZ 


/Timed read eKPiredf/ 




.END 


START 



SXfer 1st character 

rCancel .HRKT 

jTurn on TT! Special mode 

fFlush TT! ring buffer 

jputtina characters in user buffer 

»If Bore chsrj So Set 'em 

jTerminate input with null bate 

fClear bits in JSU 

fSet carra if tined out 

rReturn to caller 

iLesve conpletion code 
JExtrs Q-Element 
fEMT Araunent block for .TWAIT 
JEMT Argument block for .MRKT 
jTiae-out interval (10 sec) 
fi/60 sec wait between .TTINRs 
/ iDuBika response 
rUser input buffer 
jPro»pt 
»Too bad messaae 



2.44 .MTATCH (Special Feature) 

The .MTATCH request attaches a terminal for exclusive use by the request- 
ing job. This operation must be performed before any job can use a terminal 
with multi-terminal programmed requests. If .MTATCH request fails because 
the terminal is owned by another job, the job number of the owner is returned 
in RO. 

Macro Call: .MTATCH area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the optional address of an asynchronous terminal status word, 
or it must be 0. (The asynchronous terminal status word is a 

f'^ +l^Q+ ^rr\^t nov* ocilckfif flMvina +Vtp QVofPTn crpTlPrptlOn 






process.) 

unit is the logical unit number of the terminal. (The logical unit 
number is the number assigned by the system to a particular 
physical unit during the system generation process.) 



Request Format: 
RO -► area: 



37 5 


addr 


unit 



Errors: 



Code Explanation 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 
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Code Explanation 

4 Unit attached by another job (job number returned in RO). 

5 In the XM monitor, the optional status word address is not in 
valid user virtual address space. 



Example: 



MTXAMP.MAC - The following is an example prodratii that 
demonstrates the use of the w u 1 1 i - 1 e r m i n a 1 
prosramwed requests. The prosram attaches all the 
terminals on a S i u e n system) then proceeds w i t h a n 
in put /echo exercise on all attached terminals until 
CTRL/C is sent to it. 



.MCALL 
.HCALL 

HNGUP$ 

TTSPC$ 

TTLC* 

AS, INP 

M.TSTS 

M,TSTW 

M.NLUN 

MTKAMP: 



-MTATCH ..MTPRNT , , MTGET > . MT I N , . MTOUT 
.PRINT ,,HTRCTD ..MTBET . . MTSTAT , . EM IT 



10$; 



20$: 



30$ 



LOOP; 



10$; 



ilOOO 

1 0000 

ilOOOO 

4 



7 

IX 



-MTSTAT 
MOM 
BED 
CLR 
MOO 

.MTATCH 
BCC 
CLRB 
BR 

MOUB 
MOU 
ABL 
ASL 
ASL 
ADD 

. MTGET 
BIS 

.tITSET 

BITB 

BNE 

.MTRCTO 

.MTPRNT 

ADD 

INC 

CMP 

BLO 



CLR 
MOM 
TSTB 
BEO 



»MTA .ttMSTAT 

MSTAT + M.NLIJN.R4 

MERR 

Rl 

• AST ,R2 

*MTA »R2,R1 

20$ 

TAI (Rl ) 

30$ 

*1 fTAI (Rl) 

Rl fR3 

R3 

R3 

R3 

»TSB >R3 

»NTA tR3 tRl 

«TTSPC$+TTLC$ 



; T e r m i n a 1 off-line bit 
iSpecial mode bit 
iLower-case mode bit 
i I n p L! t available bit 
j T e r m i n a 1 status word 
i T e r m i n a 1 state byte 
;« of LUNs word 

; S t a r t of program 

;Get MTTY status 

;R4 = f* LUNs 

;None? Not MTTY ! ! ! 

; Initial LUN = «0 ■ 

iR2 -» AST word array 

JAttach terminal 

i S u c c e s s ! 

iSet attach failed 

jProoeed with next LUN 

JAttach successful 

;Copy LUN 

; M u 1 t i p 1 y by 8 for offset 



terminal s t a t u s 



M, 



»MTA »R3 (Rl 

«HNGUP$/iaOO ,M 

30$ 

#MTA >R1 

«MTA tSHELLO ,R 

#2 ,R2 

Rl 

Rl »Ril 

10$ 



Rl 

«AST »R2 
TAI (Rl) 
20$ 



5 1 the 

i b 1 c k . . . 

;R3 - LUN's TSB 

SGet LUN's status 

TSTS(R3) ;Set special 

imode and lower case 

;Set LUN's status 
.TSTW(R3) iOn line? 

; No pe ! 

;Reset CTRL/0 
1 ;Say hello... 

iR2 - Next AST word 

! G e t next LUN 

; D n e ? 

iNope. So attach another 

) I n p u t 5; echo forever 
; Initial LUN = 
;R2 -. AST words 
i T e r fi) i n a 1 attached? 
i No pe . , . 
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:0$: 



ERR: 
MERR: 

AST; 
TAI : 



MSTAT: 
TSB: 

MTA: 
MTCHAR: 

HELLO: 

NOMTTY; 

> I ki I— \/ n , 
U IN D A r i 



BIT 

BEO 

.MTIN 

BCS 

.MTOUT 

BCS 

ADD 

INC 

CMP 

BLQ 

BR 

.PRINT 
.EXIT 
.PRINT 
.EXIT 

,BLKW 

.BLKB 



.BLKW 
.BLKW 

.BLKW 
.BYTE 

.ASCII 
.fiSCIZ 
.ASCIZ 
.ASCIZ 



»AS. INP .(R2) 

20* 

*MTA t»t1TCHAR .Rl 

ERR 

«MTA .wMTCHAR jRl 

ERR 

»2 tR2 

Rl 

Rl tR4 

10$ 

LOOP 

«UNEXP 

#NDMTTY 



IB. 
IG. 



8. 
1E.*4, 

a 





; A n y i n p u t ? 
; N p p . . . 

. « 1 i I n p u t a char a 
SOoops! Error on 

.«1 iEcho the cha 
■Ooops! Error on 
■Point to next AS 
;Get next LUN 
i D n e the m all? 
; N » do c h e c K a n o 
! Y e s » repeat (for 



t e r 
i n p u t 
r a c t e r 
u t p u t 
T w r d 



t he r 
e y e r ! ) 



; U n e X p e c t e d error... 
iPrint iTiessase & exit! 
i N t rii u 1 1 i - t e r m i n a 1 
i P r i n t ill e s s a S e & exit 

; A s y n h r o n u s T e r m i n a 1 

;Status Words (l/LUN) 

; T e r m i n a 1 attached list 

i 1 Byte per LUN. , , 

;0 = Not attached 

;MTTY status block 

? T e r (Ti i n a 1 s t a t u s blocks 

! 1 B . blocks of 4 words 

; E M T a r d u. Ill e n t bloc k 

; C h a r a c t e r stored here 



<33>"H"<33>" J" iMTSZ Home + Erase to E05 
/Hello! Characters typed will be echoed/ 
/ ? N t m u 1 1 i - t e r w i n a 1 s y s t e m ? / 



,END 



MTXAMP 



e r r G r ( i . p r o S r a « aborting" 



! E n d of program 



2.45 .MTDTCH (Special Feature) 

rru^ ix/TTnTim-i ,.pr.nQo+ rip+o/^Vioo a +orrninnl frnnn nnfi ioh and makes it avail- 
able for other jobs. When a terminal is detached, it is deactivated, and unsoli- 
cited interrupts are ignored. Input is disabled immediately, but any charac- 
ters in the output buffer are printed. Attempts to detach a terminal attached 
by another job result in an error. 

Macro Call: .MTDTCH area,unit 

where: 

area is the address of a three-word EMT argument block 

unit is the logical unit number {lun) of the terminal to be detached 

Request Format: 

RO -» area: 



37 6 


unused 


— unit 
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Errors: 

Code 

1 

2 

3 

Example: 



Explanation 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 



START; 



1$: 



.MCALL .MTDTCH t.MTPRNT ..MTATCH » , EX I T . . PRINT 



.MTATCH «HTAt*0f#3 

BCC 1$ 

.MTPRNT «MTA ,#MESS ,#3 

.MTDTCH «riTA t«3 

.EXIT 

.PRINT *ATTERR 



jattach td lun 3 
;attach error 
;print message 

;DETACH LUN 3 

;ATTACH ERROR 
mPRINTEO on CONSOLE) 





.EXIT 


ATTERR: 


.ASCIZ/ATTACH ERROR/ 


MESS: 


.ASCIZ/DETACHING TERMINAL/ 




.EMEN 


MTA: 


.BLKW 3 




.END START 



2.46 .MTGET (Special Feature) 

The .MTGET request returns the status of the specified terminal unit to the 
caller. If a .MTGET request fails because the terminal is owned by another 
job, the job number of the owner is returned in RO. 

Macro Call: .MTGET area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the address of a four- word status block where the status infor- 
mation is returned 

unit is the logical unit number (lun) of the terminal whose status is 
requested. A unit need not be attached to the job issuing a 
.MTGET request. If the unit is attached to another job (error 
code 4), the terminal status will be returned and the job number 
will be contained in RO. In any other error condition, the con- 
tents of RO are undefined 

Request Format: 

RO " ares 



37 1 1 


addr 


— unit 
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The status block has the following structure: 



M.TSTS 


M.TST2 


M.FCNT 


M.TFIL 


M.TSTW M.TWID | 



addr- 



The following information is contained in the status block: 
Byte Offset Description 

(M.TSTS) Terminal configuration word 1 

2 (M.TST2) Terminal configuration word 2 

4 (M.TFIL) Character requiring fillers 

5 (M.FCNT) Number of fillers 

6 (M.TWID) Carriage width 

7 (M.TSTW) Terminal status byte 

Note that if an error occurs, and the error code is not 1 or 4, the status block 
will not have been modified. 

NOTE 

Use the Bit Set (BIS) and Bit Clear (BIC) instructions instead 
of Move (MOV) and Clear (CLR) instructions when setting 
terminal and line characteristics. This avoids changing other 
bits inadvertently. 

The bit definitions for terminal configuration word 1 (M.TSTS) are as follows: 



Value 



Bit 



1 





2 


1 


4 


2 


10 


3 


100 


6 


200 


7 


7400 


8-11 



Meaning 

Terminal has hardware tab 

Output RETA^F when carriage width exceeded 

Terminal has hardware form feed 

Process CTRL/F and CTRL/B (and CTRL/X if system job) 

as special command characters (if clear, CTRL/F and 

CTRL/B are treated as ordinary characters) 

Inhibit TT wait (similar to bit 6 in the Job Status Word) 

Enable CTRL/S - CTRL/Q processing 

Line speed (baud rate) mask. Bits 8 through 11 indicate the 

terminal baud rate (DZll and DZVll only). The values are 

as follows: 



Octal Value of 

Line Speed Mask 

(M.TSTS bits 11-8) 

0000 
0400 
1000 

1 Ar\c\ 

2000 
2400 
3000 



Baud Rate 

50 
75 
110 
134.5 
150 
300 
600 



Programmed Request Description and Examples 2-73 



Octal Value of 

Line Speed Mask 

(M.TSTS bits 11-8) 

3400 
4000 
4400 
5000 
5400 
6000 
6400 
7000 
7400 



Baud Rate 

1200 
1800 
2000 
2400 
3600 
4800 
7200 
9600 
(unused) 



10000 

20000 
40000 



12 

13 

14 



Character mode input (similar to bit 12 in the Job Status 

Word) 

Terminal is remote (Read Only bit) 

Lower to upper case conversion disabled 



100000 15 Use backspace for rubout (video type display) 

The bit definitions for terminal configuration word 2 (M.TST2) are as follows: 



Value 

3 



Bit 

0-1 



Meaning 

Character length, which can be 5(00), 6(01), 7(10), or 8(11) 

bits (DZ only) 

Unit stop, which sends one stop bit when clear, two stop 

bits when set (DZ only) 

Parity enable (DZ only) 

Odd parity when set; even parity when clear 

Reserved 

Read pass all 

Reserved 

Write pass all 

The bit definitions for terminal status byte (M.TSTW) are as follows: 



10 

20 

140 

200 

77400 

100000 



3 

4 

5-6 

7 

8-14 

15 



Value 

2000 
4000 
10000 
40000 

100000 
Errors: 



Bit 

10 
11 
12 
14 

15 



Meaning 

Terminal is shared console 

Terminal has hung up 

Terminal interface is DZll 

Double CTRL/C was struck (the .MTGET request resets 

this bit in the terminal control block if it is on) 

Terminal is acting as console (local DLll only) 



Code 

1 
2 
3 



Explanation 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

Invalid request; function code out of range. 
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Code Explanation 

4 Unit attached by another job (job number returned in RO). 

5 In the XM monitor, the status block address is not in valid user 
virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 



2.47 .MTIN (Special Feature) 



The .MTIN request reads characters from the keyboard buffer. It is the multi- 
terminal form of the .TTYIN request. The .MTIN request moves one or more 
characters from the input ring buffer to a buffer specified by you. The termi- 
nal must be attached and an updated user buffer address is returned in RO if 
the request is successful. If bit 6 is set in the M.TSTS word (see the MTSET 
request), the .MTIN request returns immediately with the carry bit set (code 
0) if there is no input available. Operation is similar for the system console if 
bit 6 is set in the JSW. If bit 12 in M.TSTS is clear, no line is available; if bit 
12 is set, there are no characters in the buffer. If these conditions do not exist, 
the .MTIN request waits until input is available, and the job is suspended 
until input is available. 

The meaning of bits 6 and 12 in the terminal configuration word (M.TSTS) 
for the programmed request .MTIN is as follows: 

Bit 6 Bit 12 Meaning 

Normal mode of input (echo provided) ; wait for line 

1 Carry bit set: no line available 

1 1 Carry bit set: no character available; no echo pro- 

vided 

1 No echo provided 

If a multiple-character request was made and the number of characters re- 
quested are not available, the request can either wait for the characters to 
become available, or it can return with a partial transfer. If bit 6 of M.TSTS 
is clear, the request waits for more characters. If bit 6 is set, the request 
returns with a partial transfer. In the latter case, RO contains the updated 
buffer address (pointing past the last character transferred), the C bit is set, 
and the error code is 0. 

The .MTIN request has the following form: 

Macro Call: .MTIN area,addr,unit[,chrcnt] 

where: 

area is the address of a three-word EMT argument block 
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addr is the byte address of the user buffer 

unit is the logical unit number of the terminal input 

chrcnt is a character count indicating the number of characters to 
transfer. The valid range is from 1 to 255 (decimal). A charac- 
ter count of zero means one character 



Request Format: 
RO -* area: 



Errors: 

Code 




37 2 


addr 


chrcnt [ unit 



Explanation 



No input available — bit 6 is set in the Job Status Word (for 
the system console) or in M.TSTS by the .MTSET request. 

1 Illegal unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 

5 In the XM monitor, the user buffer address is not in valid user 
virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 



2.48 .MTOUT (Special Feature) 

The .MTOUT request transfers characters to the terminal output buffer. This 
request is the multi-terminal form of the .TTYOUT request. The .MTOUT 
request moves one or more characters from the user's buffer to the output ring 
buffer of the terminal. The terminal must be attached. An updated user 
buffer address is returned in RO if the request is successful. When there is no 
room in the output ring buffer, the carry bit is set and an error code of is 
returned in byte 52 if bit 6 is set in M.TSTS. Otherwise, the job is suspended 
until room becomes available. 

If a multiple-character request was made and there is not enough room in the 
output ring buffer to transfer the requested number of characters, the request 
can either wait for enough room to become available, or it can return with a 
partial transfer. If bit 6 in M.TSTS is clear, the request waits until it can 
complete the full transfer. If bit 6 is set, the request returns with a partial 
transfer. In the latter case, RO contains the updated buffer address (pointing 
past the last character transferred), the C bit is set, and the error code is 0. 
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The meaning of bit 6 in the terminal configuration word (M.TSTS) for the 
.MTOUT request is as follows: 

Bit 6 Meaning 

Normal mode for output; wait for room in buffer 

1 Carry bit set: no room in output ring buffer 
Macro Call: .MTOUT area,addr,unit[,chrcnt] 

where: 

area is the address of a three-word EMT argument block 

addr is the address of the caller's input buffer 

unit is the unit number of the terminal 

chrcnt is a character count indicating the number of characters to 
transfer. The valid range is from 1 to 255 (decimal) 

Request Format: 

RO ->■ area: 



37 3 


addr 


chrcnt unit 



Errors: 

Code Explanation 

No room in output buffer. 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 

5 In the XM monitor, the user buffer address is not in valid user 
virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 

2.49 .MTPRNT (Special Feature) 

This .MTPRNT request allows one or more lines to be printed at the specified 
terminal in a multi-terminal environment. It is equivalent to the .PRINT 
request (see .MTSET request for more details). The string to be printed must 
be terminated with a null byte or a 200 byte, similar to the string used with 

liic .JTIviiN X icqucot ao luiiowo. 



or 



.ASCIZ /string/ 
.ASCII /string/<200> 
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The null byte causes a carriage return/line feed combination to be printed 
after the string. The 200 byte suppresses the carriage return/line feed combi- 
nation and leaves the carriage positioned after the last character of the string. 
The request does not return until the transfer is complete. 

Macro Call: .MTPRNT area,addr,unit 

where: 

area is the address of a three-word EMT argument block 

addr is the starting address of the character string to be printed 

unit is the unit number associated with the terminal 

Request Format: 
RO -» area: 



Errors: 

Code 

1 
2 
5 



37 7 


addr 


— unit 



Explanation 

Invalid unit number, unit not attached. 

Nonexistent logical unit number. 

In the XM monitor, the character string address is not in valid 
user virtual address space. 



Example: 

Refer to the example for the .MTATCH request. 



2.50 .MTRCTO (Special Feature) 

The .MTRCTO request resets the CTRL/0 switch of the specified terminal 
and enables terminal output in a multi-terminal environment. It is equivalent 
to the .RCTRLO request. 

Macro Call: .MTRCTO area,unit 

where: 

area is the address of a three-word EMT argument block 
unit is the unit number associated with the terminal 



Request Format: 
RO -♦ area: 



37 4 


unused 


— unit 
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Errors: 

Code Explanation 

1 Invalid unit number, unit not attached. 

2 Nonexistent logical unit number. 

3 Invalid request; function code out of range. 
Example: 

TJofcT- +/-. +V.O ovamnlo fnr tVio MTATPH rpmipst 



2.51 .MTSET (Special Feature) 

This multi-terminal request sets terminal and line characteristics. It also 
determines the input/output mode of the terminal service requests for the 
specified terminal. 

Macro Call: .MTSET area,addr,unit 
where: 

area is the address of a three-word EMT argument block 

addr is the address of a four-word status block containing the line and 
terminal status being requested 

unit is the logical unit number associated with the line and terminal 

Request Format: 
RO -♦ area: 



37 


1 







unit 



When the program returns from the request, the status block contains the 
following information: 

Byte Offset Contents 

Terminal configuration word 1 (The bit definitions are 

the same as those for the .MTGET request.) 

2 Terminal configuration word 2 (The bit definitions are 

the same as those for the .MTGET request.) 

4 Character requiring fillers 

5 Number of fillers 

6 Carriage width (byte) 
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NOTE 

The .MTSET request sets all of the parameters listed above. 
The recommended procedure for using .MTSET is: (1) precede 
it by an .MTGET request; (2) use BIS or BIG instructions to 
set or clear bit fields (modify only the bits or bytes that you 
intend to change); (3) issue the .MTSET request to replace the 
previous terminal status with the updated status. 

Note that if an error occurs, and the error code is not 1 or 4, the status block 
will not have been modified. 

Errors: 

Code Explanation 

1 Illegal unit number, lun not attached. 

2 Nonexistent logical unit number. 

3 Illegal request, function code out of range. 

5 In the XM monitor, the status block address is not in valid user 
virtual address space. 

Example: 

Refer to the example for the .MTATCH request. 



2.52 .MTSTAT (Special Feature) 

The .MTSTAT request returns multi-terminal system status information. 

Macro Call: .MTSTAT area,addr 

where: 

area is the address of a three-word EMT block 

addr is the address of an eight-word status block where multi-termi- 
nal status information is returned. The status block contains the 
following information: 

Byte Offset Contents 

Offset from the base of the resident monitor to 

the first terminal control block (TCB) 

2 Offset from the base of the resident monitor to 

the terminal control block of the console termi- 
nal for the program 

4 The number of terminal control blocks built into 

the system (1-17 decimal) 
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Byte Offset Contents 

6 The size of tue terminal controi ulock in uytes 

10-17 Reserved 



Request Format: 
RO -► area: 



37 10 



addr 



Code 



Explanation 



5 In XM, the status block address is not in valid user address 
space. 

Example: 

Refer to the example for the .MTATCH request. 



2.53 .MWAIT(FB and XM Only) 

This request is similar to the .WAIT request. .MWAIT, however, suspends 
execution of the job issuing the request until all messages sent to the other job 
or requested from the other job have been received. It should be used prima- 
rily in conjunction with the .RCVD or .SDAT modes of message handling, 
where no action is taken when a message is completed. 

Macro call: .MWAIT 

Request Format: 



RC 



11 





Errors: 



None. 



Example: 



.MHAIT - This is an example in the use of the .HUAIT reauest. 
The exsnple is sctusll^j two proarsmsi s Backslound Job 
which sends messaSesj and a Foreground Jobr which receives thero. 
NOTEI Each proSram should be asseabled and linked separately. 



•TITLE MUAITF.M6C 
! + 
i Forearound F'roaraiii ... 



.MCALL .RCVn. .MWAIT. .PRINT, .EXIT 



MUAITF: .RCVD »AREAr*MBUFF.*40. 



SReQuest a messaSe up to 80 char. 

»No error possible - alwaus a B6 

f 

JDa so»e other processina 
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.PRINT 
r 


♦FGJOB 




9 

.hWAIT 


• 




TST 


MBUFF+2 




BEG 


FEXIT 




•PRINT 


»F«S6 




.PRINT 


♦HBUFF+2 




BR 


MWAITF 


FEXIT! 


.EXIT 




area; 


.BLKU 


5 


mbuff: 


.BLKU 


41. 




.UORIi 





F6J0B! 


.ASCIZ 


/Hi - FG 


FMSG! 


.ASCIZ 


/Hes BG 




.END 


MWAITF 



ilike snnouncina FG active. 



iUait for messeae to arrive... 
$NulI iiiesssae? 
j Yes . . . eHit the proarsm 
lAnnounce we Sot the messase... 
iand echo it back 
jLoop to set another one 
(Exit proaram 
jEMT Araument Block 
SBuffer - Msa lenath + 1 
rMake sure 80 char nessaae ends ASCIZ 
- FG alive and well and uaitina for a messaae!/ 



Got your nessaae it reads!/ 



.TITLE MWAITB.MAC 



; + 

» Bscksround Proaran 



Send a 'null' messaae to stop both proarans 





.MCALL 


.SDATkMUAITf.G 


muaitb: 


CLR 


BUFF 




.GTLIN 


*BUFF»*PROMT 




.SDAT 


*AREAi*BUFF.*40 




BCS 


1* 




.MUAIT 






TST 


BUFF 




BNE 


MUAITB 




.EXIT 




i«: 


.PRINT 
.EXIT 


♦ NOFG 


area: 


.BLKU 


5 


buff; 


,BLKW 


40, 


promt; 


.ASCII 


/Enter messaae 


NOFG! 


.ASCIZ 


/?No FG?/ 




.END 


MUAITB 



to be 



iClear 1st word 

jGet somethina to send to FG from TTY 
fSend input as messaae to FG 
■Branch on error - No FG 
■Uait for messaae to be sent 
JSent a null messaae? 
JN0...I00P to send another messaae. 
J Yes . . . exit proaram 
.'No FG ! 
jExit proaram 
JEMT Araument Block 
!Up to 80 char messaae 
sent to FG Job/<15><12>/>/<200> 



2.54 .PRINT 



The .PRINT request causes output to be printed at the console terminal. The 
string to be printed can be terminated with either a null (0) byte or a 200 byte. 
If the null (ASCIZ) format is used, the output is automatically followed by a 
carriage returnAine feed combination. If a 200 byte terminates the string, no 
carriage return/line feed combination is generated. 

Control returns to the user program after all characters have been placed in 
the output buffer. 

When a foreground job is running and the job that is producing output 
changes, a B> or F> appears. Any text following the message has been printed 
by the job indicated (foreground or background) until another B> or F> is 
printed. 

When a system job prints a message to the terminal, the message is preceded 
by logical-job-name. 

If the foreground job issues a message using .PRINT, the message is printed 
immediately, no matter what the state of the background job. Thus, for ur- 
gent messages, the .PRINT request should be used (rather than .TTYOUT or 
.TTOUTR). The .PRINT request forces a console switch and guarantees 
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printing of the input line. If a background job is doing a prompt and has 
printed an asterisk but no carriage return/line feed combination, the console 
belongs to the background and .TTYOUTs from the foreground are not 
printed until a carriage return is typed to the background. The foreground job 
can force its message through by doing a .PRINT instead of the .TTYOUT. 

Macro Call: .PRINT addr 



where: 



addr is the address of the string to be printed 



nrrors: 

None. 
Example: 

.TITLE PRINT. HAC 

S + 

f .PRINT - This is an exaiiPle in the use of the .PRINT reouest. 
f The exsRple merely scep-ts input from the console terminsl and 
i echoes it back. 



.MCALL .GTLINf. PRINT, .EXIT 



START! .GTLIN *BUFFr*PROMT 





TSTB 


BUFF 




BEQ 


1» 




.PRINT 


♦ BUFF 




CLRB 


BUFF 




BR 


START 


1$: 


.EXIT 




buff: 


.BLKU 


41. 


PROMT! 


.ASCII 


/Ente 




.END 


START 



»Get 3 line of input from keyboard 



SNothins entered? 
fBranch if nothina entered 
JEcho the input back 
rClear first char of buffer 
JGo back for more 
fExit program on null input 
J80 character buffer (ASCIZ for .PRINT) 
/Enter somethina/<12><15>/>/<200> 



2.55 .PROTECT/.UNPROTECT (FB and XM Only) 

.PROTECT 

The .PROTECT request allows a job to obtain exclusive control of a vector 
(two words) in the region 0-476. If the request is successful, it indicates that 
the locations are not currently in use by another job or by the monitor. The 
job then can place an interrupt address and priority into the protected loca- 
tions and begin using the associated device. 

Macro Call: .PROTECT area,addr 

where: 

area is the address of a three-word EMT argument block 
addr is the address of the word pair to be protected 

NOTE 

The argument addr must be a multiple of four, and must be 
less than 476 (octal). The two words at addr and addr+2 are 
protected. 
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Request Format: 
RO -► area: 



31 



addr 



addr+2 



Errors: 



Code Explanation 

Protect failure; locations already in use. 

1 Address (addr) is greater than 476 or is not a multiple of 4. 



Example: 



.TITLE PROTEC.MAC 



.PROTECT / .UNPROTECT - This is an exBBPle in the use of the .PROTECT 
and .UNPROTECT reouests. The exsBPle illustrates how to protect the 
vectors of a device while an inline interrupt service routine does 
3 data transfer (in this case the device is a DLll Serial Line Interface). 
When the proara» is finished? the vectors are unprotected for possible 
use bu another Job. 



.HCALL .DEyiCE. .EXITj .PROTECTf .UNPROTECT, .PRINT 
.DEVICE *AREA,*LIST 



.PROTECT *AREA,*300 
BCS BUSY 



start; .device *AREA,*LIST fSetup to disable DLll interrupts on 

j.EXIT or "C"C 
fProtect the DLll vectors 
fBranch if alreada protected 
rSet UP data to transmit over DLll 

lUse DLil xfer routine (see .INTEN exaaple) 
f ArauBients . . .Word count 
jData buffer addr 
^Continue processing... 

!.. .eventually to e^it proaram 

fprint error nessaSe... 

rthen exit 

fEMT Arsunent block 

;CSR of DLll 

SStuff it with '0' 

rList terminator 
BUFFR! JData to send over DLll 

.REPT 8. f8 lines of 32 characters... 

.ASCIZ /Hello DLll ... Are You There ??/ 
.ENDR 
NOVEC; .ASCIZ /?Veetor alreadij protected?/ S Error roessase text 





jsr 


RSfDLII 




.WORD 


128, 




.WORD 


BUFFR 


FiNi: 


i 

.UNPROTECT ♦AREAt*300 




.EXIT 




busy: 


.PRINT 
.EXIT 


♦NOUEC 


area: 


.BLKU 


3 


list: 


.WORD 


176500 




.UORD 







.WORD 






.END 



START 



.UNPROTECT 

The .UNPROTECT request is the complement of the .PROTECT request. It 
cancels any protected vectors in the to 476 area. An attempt to unprotect a 
vector that a job has not protected is ignored. 

Macro Call: .UNPROTECT area,addr 

where: 

area is the address of a two-word EMT argument block 
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addr is the address of the protected vector pair that is going to be 
canceled. The argument addr must be a multiple of four, and 
must be less than 476 (octal) 

Request Format: 

RO ->■ area: 



31 



addr 



Errors: 



Code 



Explanation 



1 Address {addr) is greater than 476 (octal) or is not a multiple of 
four. 

Example: 

Refer to the example for the .PROTECT request. 



2.56 .PURGE 



The .PURGE request deactivates a channel without performing a .HRESET, 
.SRESET, .SAVESTATUS, or .CLOSE request. It frees a channel without 
taking any other action. If a tentative file has been entered on the channel, it 
is discarded. An attempt to purge an inactive channel is ignored. 

NOTE 

Do not purge channel 17 (octal) if your program is overlaid 
because overlays are read on that channel. 

Macro Call: .PURGE chan 



chan is the number (octal) of the channel to be freed 
Request Format: 
RO = 



chan 



Errors: 



None. 
Example: 

•TITLE PURGE. hAC 

; + 

i .PURGE - This is an example in the use of the PURGE reouest. 

( This example merges 2-6 files into 1 filej nskinS use of .SrtMESTATUS 

( and .REOPEN to read all input files on one channel. The .PURGE reouest 

i is used to free the input channel after each transfer. 



.hCALL . OS I GEN r. SAVESTATUS I .REOPEN. .CLOSE. .EXIT 
.MCALL .REAnW..WRITHF .PRINT. .PURGE 
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ERRBYT 


= 52 


start: 


.csigen 


♦DSPACE.tDEFEXT 




Moy 


♦ 3fR4 




MOM 


•AREAfR3 




MOV 


*SAVBLKfR5 


1$: 


•SAVEST 


R3fR4.R5 




BCS 


2» 




ADD 


»12fR5 




INC 


R4 




CMP 


*8, >R4 




B6E 


1* 


2*! 


Moy 


*SAVBLK»R5 




BEQ 


7« 


A*l 


.REOPEN 


R3f*3>R5 




CLR 


BLK 


5*: 


.READU 


R3>*3»*BUFFRf*25 




BCC 


6$ 




TSTB 


e*ERRBYT 




BNE 


8« 




.PURGE 


«3 




ADD 


#12. R5 




TST 


eR5 




BNE 


4* 




.CLOSE 


*0 




•PRINT 


♦ DONE 




.EXIT 




6«: 


.URITU 


R3.*0.*BUFFR,*25 




INC 


UBLK 




INC 


BLK 




BCC 


5$ 




MOM 


*WERR>RO 




BR 


9» 


7«: 


MOM 


*NOINP»RO 




BR 


9$ 


a*: 


MOV 


♦RERRfRO 


9$: 


.PRINT 
.EXIT 




area: 


.BLKW 


5 


blk; 


.UORD 





ublk: 


.WORD 





samblk: 


:.BLKU 


30. 


defext: 


.UORD 


O.OjOfO 


noinp: 


.ASCIZ 


/?No input files 


uerr: 


.ASCIZ 


/TUrite Error?/ 


RERR! 


.ASCIZ 


/TRead Error?/ 


done: 


.ASCIZ 
.EVEN 


/I-O Trensfer Co 


buffr: 


.BLKU 


256, 


nspftCE 


~ ¥ 





(Error bate loc in SYSCOM 

Get file specsfopen files>lo3d handlers 

R4 = 1st input channel 

R3 => EMT Arsument block 

R5 => Channel savestatus blocks 

Ssve channel status 

Branch if channel never opened 

Adjust R5 to point to next status block 

Bump R4 to = next input channel 

Done all input channels? 

Branch if not 

R5 => to 1st saved channel status 

Branch if no input files 

Re-open input channel on Ch 3 

Start reading with block 

i.iBLK fRead a block 

Branch if no error 

Check if error = EOF 

Branch if not EOF 

Clear input channel for re-use 

Point R5 to next saved ch status 

Ana iiore input channels? 

Branch if aes 

We're done... close output channel 

Announce nerSe complete 

Exit proaram 

i. jUBLK JWrite block Just read 

Bump to next output block 

same for input blk (doesn't affect C bit) 

Branch if no error on write 

Write error - RO => message 

ner^e. . . 

RO => No input files message 

merge . . . 

RO => Read error message 

Report error 

then exit program 

EMT Argument block 

Current read block 

Current write block 

Saved channel status area 

No default extensions for CSIGEN 



jI/0 buffer 
rHandlers start here. 



.END 



START 



2.57 .QELDF (Device Handlers Only) 

The .QELDF macro symbolically defines queue element offsets for the speci- 
fied set of system generation special features. The queue element offsets gen- 
erated by this macro are as follows: 



Q.LINK=0 

Q.CSW=2. 

Q.BLKN=4. 

Q.FUNC=6. 

Q,JNUM=^7. 

Q.UNIT=7. 

Q.BUFF='O10 



(Link to next queue element) 

(Pointer to channel status word) 

(Physical block number) 

(Special function code) 

(Job number) 

(Device unit number) 

(User virtual memory buffer address) 
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Q.WCNT='012 (Word count) 
Q.C0MP=*014 (Completion routine code) 

Since the handler usually deals with queue element offsets relative to 
Q.BLKN, the .QELDF macro also defines the following symbolic offsets: 

Q$LINK=-4 

Q$CSW=-2 
Q$BLKN=0 

Q$FUNC=2 
Q$JNUM=3 

Q$BUFF=4 

Q$WCNT=6 

Q$COMP='OlO 

For SJ and FB systems: 

Q.ELGH='016 (End of queue element; used to find length) 

For XM systems: 

Q.PAR=*016 (PARI relocation bias) 

Q$PAR='012 

Q.ELGH="024 (End of queue element; used to find length) 

NOTE 

Be sure to invoke .QELDF after you specify the system condi- 
tional defaults, because the queue element offsets are different 
if you select memory management by setting MMG$T = 1. The 
.DRDEF macro automatically invokes .QELDF in a handler. 

Example: 

Refer to the example following the description of .DRAST. 



2.58 .QSET 



The .QSET request allows additional entries to be made to the RT-U I/O 
queue. A general rule to follow is that each program should contain one more 
queue element than the total number of I/O requests that will be active 
simultaneously on different channels. Timing and message requests such as 
.MRKT, .TWAIT, .SDAT/C, and .RCVD/C also require queue elements and 
must be considered when allocating queue elements for a program. Note that 
if synchronous I/O is done (such as .READW/.WRITW) and no timing re- 
quests are done, no additional queue elements need be allocated. 

Each time .QSET is called, a specified contiguous area of memory is divided 

llil/VJ OC V Cll- WUIU. OCglll'CJ.lL'b \XU- Wv/lU. L*-*CVlli.lCilj aCgiAlVi.Xl/0 AV/x fxiv -t^i.l'J. AXxvJxiiiyvyi / 

and is added to the queue for that job. .QSET can be called as many times as 
required. The queue set up by multiple .QSET requests is a linked list. Thus, 
.QSET need not be called with strictly contiguous arguments. The space used 
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for the new elements is allocated from your program space. Care must be 
taken so that the program in no way alters the elements once they are set up. 
The .SRESET and .HRESET requests discard all user-defined queue ele- 
ments; therefore any previous .QSET requests must be reissued. However, 
you must not specify the same space in two separate .QSET requests if there 
has been no intervening .SRESET or .HRESET request. 

Care should also be taken to allocate sufficient memory for the number of 
queue elements requested. The elements in the queue are altered asynchro- 
nously by the monitor; if enough space is not allocated, destructive references 
occur in an unexpected area of memory. The monitor returns the address of 
the first unused word beyond the queue elements. Other restrictions on the 
placement of queue elements are that the USR must not swap over them and 
they must not be in an overlay region. For jobs that run under the XM 
monitor, queue elements must be allocated in the lower 28K words of mem- 
ory, since they must be accessible in kernel mapping. In addition, the ele- 
ments must not be in the virtual address space mapped by kernel PARI, 
specifically the area from 20000 to 37776(octal). 

NOTE 

Programs that are to run in both FB and XM environments 
should allocate 10 (decimal) words for each queue element. 
Alternatively, a program can specify the start of a large area 
and use the returned value in RO as the top of the queue ele- 
ment. 

The following programmed requests require queue elements: 



.TWAIT 


.RCVDW 


.MRKT 


.WRITE 


.READ 


.WRITC 


.READC 


.WRITW 


.READW 


.SDAT 


.RCVD 


.SDATC 


.RCVDC 


.SDATW 



Macro Call: .QSET addr,len 

wncic. 

addr is the address at which the new elements are to start 

len is the number of entries to be added. In the SJ and FB monitor, 
each queue entry is seven words long; hence the space set aside 
for the queue should be len*l words. In the XM monitor, 10 
(decimal) words per queue element are required 

On completion, RO contains the address of the first word beyond the allocated 
queue elements. 

Errors: 

In an extended memory environment, an attempt to violate the PARI 
restriction results in a ?MON-F-addr error, which can be intercepted 
with a .SERR programmed request. 
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Example: 



.TITLE QSET.MAC 
i + 

T .QSET - This is an exsmp-le in the use of the .QSET reauest. 
! The eKsmple illustrates 3 user implemented 'Timed Read' to cancel sn 
i input reouest sfter 3 specified time interval. 

.MCALL .MRKT. . TTINR, .EXIT .. PRINT r .TTYOUT, .CMKT, .TWAITi .QSET 





LF = 12 






JSW = 44 




TCBIT* 


= 100 




TTSPC* 


= 10000 


START! 


• QSET 


*XQUEr*l 


1*: 


HOV 


♦PROhTfRO 




MOU 


♦BUFFRrRl 




CALL 


TREAD* 




BCS 


2« 




.PRINT 


• LINE 




BR 


1$ 


2t: 


.PRINT 
.EXIT 


♦TIMOUT 



jLine Feed 

iJob Status Word location 
jReturn C-bit bit in JSU 
»TTY Special Mode bit in JSW 

jNeed an extra Q-Elea for this 

SMainline - RO => Prompt 

fRl => Input buffer 

»Iio a 'timed read" 

fC-bit set = Timed out 

t 'Process' data, . . 

»6o back for more 

fRead timed out - could process 

rpartial data but we'll Just exit 



TREAO*: 



i»: 



TTIN! 



TBYTi 



2«: 
3$: 



tout; 

xque: 

area: 

tarea: 

time: 

wait: 

line; 

BUFFR! 

promt: 
TIMOUT: 



f» TREAD* - 'Timed Read' Subroutine 

}* Input; RO => Prompt String / RO = if no prompt 

j* Rl => Input Buffer 

F« Output; Buffer contains input charsi if anyi terminated 

tt bs a null char. C-Bit set if timed out 



TST 
BEG 

.PRINT 
CLR 

• MRKT 
BIS 
CLRB 
.TWAIT 
.TTINR 
BIT 
.WORD 
BNE 
BCS 
MOVB 
.CMKT 
BIS 

.TTINR 
MOMB 
BCC 
CLRB 
BIG 
ROR 

RETURN 
INC 

RETURN 
.BLKW 
.WORD 

• BLKW 
.WORD 
.WORD 
.ASCII 
.BLKB 
.ASCIZ 
.ASCIZ 
.END 



RO 
1* 

TBYT 

♦TAREA. *TIMEf*TOUTf*l 

♦TCBIT*fe»JSU 

eRl 

tAREA 

*1, (PC)+ 


2* 

TTIN 

ROf (Rl)+ 

♦TAREAf*0 

♦TTSPC*. e»JSU 

R0.(R1)+ 

3* 

-(Rl) 

*TCBIT«!TTSPC*.e*JSW 

TBYT 

TBYT 



10 



4 





/N 

81 

/E 

/T 

ST 



WAIT 

600. 

1 

ot in stock - Part * 

nter Part * >/<200> 
imed read e!!pired!/ 
ART 



See if we have to prompt 

Branch if no . . . 

Output prompt 

Clear time-out flag 

Issue a .MRKT for 10 sec 

Set C-Bit bit in JSW (for F/B) 

Start with 'empty' buffer 

Wait so we don't lock out BG 

Look for a character 

Timed out? 

Time-out flaS 

Branch if aes 

Branch if input not complete 

Xfer 1st character 

Cancel .MRKT 

Turn on TT: Special mode 

Flush TTt rins buffer 

putting characters in user buffer 

If more char, go get 'em 

Terminate input with null byte 

Clear bits in JSW 

Set carry if timed out 

Return to caller 

Leave completion code 

Extra Q-Element 

EMT Argument block for .TWAIT 

EMT Araument block for .MRKT 

Time-out interval (10 sec) 

1/60 sec wait between .TTINRs 

.Dummy response 

User input buffer 

Prompt 

Too bad message 



2.59 .RCTRLO 



The .RCTRLO request makes sure that the console terminal is able to print 
by resetting the CTRL/0 switch for the terminal. A CTRL/0 typed while 
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output is directed to the console terminal inhibits the output from printing 
until either another CTRL/0 is struck or until the program resets the 
CTRL/0 switch. Therefore, a program with a message that must appear at 
the console should reset the CTRL/0 switch. 

Macro Call: .RCTRLO 

Errors: 

None. 

Example: 

.TITLE RCTRLO. MAC 
J + 

f .RCTRLO - This is 3n exsnple in the use of the .RCTRLO reouest. 
f In this e'Aanfler the user program first cslls the CSI in fienersl mode» 
Jthen processes the coniisnd. When finished? it returns to the CSI for 
fsnother conmsnd line. To aske sure that the promptina '*' taped ba 
»the CSI is not inhibited bs 3 CTRL-0 in effect from the last operstion> 
fterainal output is assured via the .RCTRLO reouest prior to the 
JCSI call. 

f - 

.MCALL . RCTRLO.. CSIGEN,. EXIT 

START5 .RCTRLO JMske sure TT: output is enabled 

.CSIGEN *DSPACE>*liEXTr*0 > Issue a .CSIGEN reouest to ^et coaaand 

J(CSI will prompt with '«') 
' . .Process the command... 

J . i ' 

y ♦ f 

JMP START jGet another command... 

DEXT5 .WORD O.O.OrO iHo default entensions 

DSPACEJ = . ;Sp3ce for handlers starts here 

.END START 



2.60 .RCVD/.RCVDC/.RCVDW (FB and XM Only) 

The .RCVD (receive data) request allows a job to read messages or data sent 
by another job in an FB environment. 

There are three forms of the .RCVD request, and they are used with the 
.SDAT (send data) request. The send data-receive data request combination 
provides a general data/message transfer system for communication between 
a foreground and a background job. .RCVD requests can be thought of as 
.READ requests where data transfer is not from a peripheral device but from 
the other job in the system. Additional queue elements should be allocated for 
buffered I/O operations in .RCVD and .RCVDC requests (see the .QSET 
request). Under an FB monitor with the system job feature, .RCVD/C/W 
requests and .SDAT/C/W requests remain valid for sending messages between 
background and foreground jobs in addition to the general read and write 
capability available to all jobs. 

RCVD 

This request is used to receive data and continue execution. The request is 
posted and the issuing job continues execution. When the job needs to have 
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the transmitted message, an .MWAIT should be executed. This causes the job 
to be suspended until the message has been received. 

Macro Call: .RCVD area,buf,wcnt 

where: 

area is the address of a five-word EMT argument block 

buf is the address of the buffer into which the message length/mes- 
sage data is to be placed 

went is the number of words to be transferred 

Request Format: 

RO ->• area: 



26 







reserved 



buf 



went 



1 



Upon completion of the .RCVD, the first word of the message buffer contains 
the number of words transmitted. Thus, the space allocated for the message 
should always be at least one word larger than the actual message size ex- 
pected. If the sending job attempts to send more words than the receiver 
specified in the went argument of the .RCVD request, the first word of the 
buffer will contain the number of words that the sender specified, but only 
went words will be actually transferred. The rest of the sender's message will 
be ignored. 

The word count is a variable number, and as such, the .SDAT/.RCVD combi- 
nation can be used to transmit a few words or entire buffers. The .RCVD 
operation is only complete when a .SDAT is issued from the other job. 

Programs using .RCVD/. SDAT must be carefully designed to either always 
transmit/receive data in a fixed format or to have the capability of handling 
variable formats. Messages are all processed in first-in first-out order. Thus, 
the receiver must be certain it is receiving the message it actually wants. 
Message handling in the FB monitor does not check for a word count of zero 
before queuing a send or receive data request. Since RT-11 distinguishes a 
send from a receive by complementing the word count, a .SDAT of zero words 
is treated as a .RCVD of zero words. Avoid a word count of zero at all times 
when using a .RCVD request. 

Errors: 

Code Explanation 

No other job exists in the system. 
Example: 

Refer to the example for the .SDAT request. 
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.RCVDC 

The .RCVDC request receives data and enters a completion routine when the 
message is received. The .RCVDC request is posted and the issuing job con- 
tinues to execute. When the other job sends a message, the completion routine 
specified is entered. 

Macro Call: .RCVDC area,buf,wcnt,crtn 

where: 

area is the address of a five -word EMT argument block 

buf is the address of the buffer into which the message length/mes- 
sage data is to be placed 

went is the number of words to be transmitted 

crtn is the address of a completion routine to be entered 

As in the .RCVD request, word of the buffer contains the number of words 
transmitted when the transfer is complete. 

Request Format: 

RO -» area: 



26 







reserved 



buf 



went 



ertn 



Errors: 

Code Explanation 

No other job exists in the system. 
Example: 



.TITLE RCVDC. MAC 



5 + 



i .RCVDC - This is an eKsnple in the use of the .RCVDC reouest. The e>i3MPle 

f is 3 sikulstion of 3 i»3inline Foreground pro3r3« which is currently 

• suspenrted usitins for a aessase froiB the PscKsround; but which needs 

J to close 3 file (perhsps opened bu 3 .ENTER ?) before sbprtina from 

f CTRL-C action. A conpletion routine periodicalls inspects the CTRL-C 

f status word and resumes the mainline if double CTRL-C is entered. 

i NOTEJ This example MUST be run ss a FG Job under an FB monitor. 

f - 

.MCALL , SCCA.. RCVDC. EXIT f. PRINT r .MRKT 
.MCALL .QSETf.SPNDf.RSUM 

START5 .QSET »QELEM.#1 iAlloc3te 3nother Q-Element 

.SCCA tMAREArtSCCA ilnhibit "CC 3ction bu monitor 

1»! CALL CMATCH iStsrt ■M3tchdoa" completion rtne 

.RCVDC «MAREAr*MBUFF»*40.7*MESG !Look for 3 mess33e 

i t iNo errors - there's 3lw3»s BG 

J . JOther processing here... 



.PRINT 
.SPND 
TST 
BNE 



♦SLEEP 



SCCA 
CLOSE 



^Announce we're goins to suspend 
iSuspend to wait for messsSe 
JHe've been .RSUMed . . ."C"C hit?? 
iBrsnch if ues 
^otherwise assume message came in. 
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i <process aessaae here> 




BR 


1« 


CUATCHi 


TST 


SCCA 




BEQ 


MARK 


mesg: 


.RSUM 
RETURN 




mark: 


.MRKT 
RETURN 


*CAREAf*TIME.*CUATCH»*l 



CLOSEt .PRINT *ABORT 
f * 
; <0utput file<s) closed here> 



JCheck if "C"C entered... 
IBrsrich if no 

»Yes...w3ke up the nainline 
Jthen leave completion code 
^Schedule to run aSsin in 10 sec. 
Sthen leave conpletion code 

JAnnounce we're aborting 
jproceed with 'orderltf' abort 



> Cvx-; + + Se 



> f« n d n aiii 



QELEMJ 


.BLKW 


7 


mbuff: 


.BLKU 


41. 


marea: 


.BLKU 


5 


carea: 


.BLKU 


4 


time: 


.UORD 


0j600 


scca: 


.UORD 





abort: 


.ASCIZ 


/?! A 


sleep: 


.ASCIZ 


/! Ma 



fExtra Q-Element 

jMessaae buffer 

jEMT Araument blocks 

5 

fTiine out in 10 seconds 

j"C"C Status word 

..Closing Output File<s) !?/ 



.END 



START 



.RCVDW 

.RCVDW is used to receive data and wait. A message request is posted and 
the job issuing the request is suspended until the other job sends a message to 
the issuing job. When the issuing job runs again, the message has been 
received, and word of the buffer indicates the number of words transmitted. 

Macro Call: .RCVDW area,buf,wcnt 

where: 

area is the address of a five-word EMT argument block 

buf is the address of the buffer into which the message length/mes- 
sage data is to be placed 

went is the number of words to be transmitted 

Request Format: 

RO -► area: 



26 







reserved 



went 







Errors: 

Code Explanation 

No other iob exists in the system. 
Example: 

Refer to the example for the .SDATW request. 
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2.61 .RDBBK (XM Only) 



The .RDBBK macro defines symbols for the region definition block and 
reserves space for it. The .RDBBK automatically invokes .RDBDF. 

Macro Call: .RDBBK rgsiz 

where: 

rgsiz is the size of the dynamic region needed (expressed in 32-word 
units) 

Example: 

See Chapter 4 of the RT-11 Software Support Manual for an example 
that uses the .RDBBK macro and a detailed description of the extended 
memory feature. 



2.62 .RDBDF (SM Only) 



The .RDBDF macro defines the symbolic offset names for the region defini- 
tion block and the names for the region status word bit patterns. In addition, 
this macro also defines the length of the region definition block by setting up 
the following symbol: 

R.GLGH = 6 

The .RDBDF macro does not reserve space for the region definition block. 

Macro Call: .RDBDF 

The .RDBDF macro expands as follows: 



R.GID 


= 


R.GSIZ 


= 2 


R.GSTS 


= 4 


R.GLGH 


= 6 


RS.CRR 


= 100000 


RS.UNM 


= 40000 


RS.NAL 


= 20000 



2.63 .READ/.READC/.READW 



Read operations for the three modes of RT-U I/O are done using the .READ, 
.READC, and READW programmed requests. 

In the case of .READ and .READC, additional queue elements should be 
allocated for buffered I/O operations (see the .QSET request). 

Upon return from any .READ, .READC, or .READW programmed request, 
RO contains the number of words requested if the read is from a sequential- 
access device (for example, paper tape). If the read is from a random-access 
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device (disk or DECtape), RO contains the actual number of words that will be 
read (.READ or .READC) or have been read (.READW). This number is less 
than the requested word count if an attempt is made to read past end-of-file, 
but a partial transfer of one or more blocks is possible. In the case of a partial 
transfer, no error is indicated if a read request is shortened. Therefore, a 
program should always use the returned word count as the number of words 
available. 

For example, suppose a file is five blocks long (it has block numbers to 4) 
and a request is issued to read 512 words (decimal), starting at block 4. Since 
512 words is two blocks, and block 4 is the last block of the file, this is an 
attempt to read past end-of-file. The monitor detects this and shortens the 
request to 256 words (decimal). On return from the request, RO contains 256, 
indicating that a partial transfer occurred. Also, since the request is shortened 
to an exact number of blocks, a request for 256 words either succeeds or fails, 
but cannot be shortened. 

An error is reported if a read is attempted starting with a block number that is 
beyond the end-of-file. The carry bit is set, and error code appears in byte 
52. No data is transferred in this case, and RO contains a zero. 

.READ 

The .READ request transfers to memory a specified number of words from the 
device associated with the specified channel. The channel is associated with 
the device when a .LOOKUP or .ENTER request is executed. Control returns 
to the user program immediately after the .READ is initiated, possibly before 
the transfer is completed. No special action is taken by the monitor when the 
transfer is completed. 

Macro Call: .READ area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-377 (octal) 

buf is the address of the buffer to receive the data read 

went is the number of words to be read 

blk is the block number to be read. For a file-structured .LOOKUP, 
the block number is relative to the start of the file. For a non- 
file-structured .LOOKUP, the block number is the absolute 
block number on the device. Note that the first block of a file or 
device is block number 0. The user program normally updates 
blk before it is used again. If input is from TT: and blk=0, TT: 
issues an uparrow (*) prompt (This is true for all .READ 
requests.) 

Notes: 

1. .READ and .READC requests instruct the monitor to do a read from the 
device by queuing a request for the device and immediately returning 
control to your program. 
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2. .READ and .READC requests execute as soon as all previous I/O requests 
to the device handlers have been completed. Note that a read from RKl: 
must wait for a previous read to RKO: to complete. This is a hardware 
restriction because the controller looks at all I/O operations sequentially. 

3. Read errors are returned from the .READ and .READC or the .WAIT 
request. Errors can occur on the read or on the wait, but only one error is 
returned. Therefore, the program must check for an error when the read is 
complete (.READ/BCS) and after the wait (.WAIT/BCS). The wait re- 
quest returns an error, but it does not indicate which read caused the 
error. 

Errors reported on the return from the read request are as follows: 

a. Nonexistent device/unit 

b. Nonexistent block 

c. In general, errors that do not require data transfers but are controller 
errors or EOF errors 

4. During the .READ and .READC requests, the monitor keeps track of 
errors in the channel status word. If an error occurs before the monitor can 
return to the caller, the error is reported on the return from the read 
request with the carry bit set and the error value in RO. If the error occurs 
after return from the read request, the error is reported on return from the 
next .WAIT, or the next .READ/.READC. Some errors can be returned 
from .READ/.READC requests immediately, before any I/O operation 
takes place. One condition that causes an immediate error return is an 
attempt to read beyond end-of-file. 

5. If .READ/C/W requests are used to receive messages under a system job 
monitor, the buffer must be one word longer than the number of words 
expected to be read. Upon completion of the data transfer, the first word 
of the buffer will contain a value equal to the number of words actually 
transferred (as for ,RCVD/C,/W), 

Request Format: 
RO ^ area: 



10 


chan 1 


blk 


buf 


went 


1 



When the user program needs to access the data read on the specified chan- 
nel, a .WAIT request should be issued as a check that the data has been read 
completely. If an error occurred during the transfer, the .WAIT request indi- 
cates the error. 
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Errors: 

Code Explanation 

Attempt to read past end-of-file. 

1 Hard error occurred on channel. 

2 Channel is not open. 

Example: 



.TITLE READ. MAC 

.READ / .WRITE - This is sn example in the use of the .READ / .WRITE 
reauests. The exsuple demonstrates ssacnhronous I/O where a mainline 
program initiates input vis .READ reouestsi does some other processing 
makes sure input has completed via the .WAIT reouest? then outputs 
the block Just read. Another .WAIT is issued before the newt read 
is issued to make sure the previous write has finished. This example 
is another single file cops proaramt utilizing .CSIGEN to input the 
file specs» load the reouired handlers and open the files. 



start: 



i«: 



2f : 



3«: 
4*: 



5»J 

i«: 



7$t 



area:: 
ioblk: 



buff: 

DEFEXTl 

done: 
messg: 
werr: 
rerr: 



.MCALL 
.MCALL 

ERRBYT 

.ENABL 

.CSIGEN 

MOU 

CLR 

.READ 

BCS 

BIT 
BNE 
.PRINT 

9 

.WAIT 

BCS 

♦WRITE 

BCS 

INC 



.READ» .WRITE, .CLOSE . .PRINT 
.CSIGEN,. EXIT, .WAIT,.SRESET 



= 52 

LSB 

*DSPACE,*DEFEXT 

♦AREA,R5 

IOBLK 

RS,*3 

6* 

«1, IOBLK 

2$ 

*MESSG 

*3 

5* 

R5>*0 
3$ 
IOBLK 



.WAIT 

BCC 

MOV 

.PRINT 

BR 

HOV 

BR 

TSTB 

BNE 

.PRINT 

.CLOSE 

•SRESET 

.EXIT 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.BLKU 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 



DSPACE = 



(Error Bate location in SYSCOM 

jEnahle local symbol block 

jUse CSIGEN to Set handlers, files 

!R5 => EMT Argument list 

(Start reads with Block *0 

(Read a block... 

(Branch on error 

•Then simulate 

(some other 

(meaninafuK?) 

(process. . . 

(Did read finish OK? 

(Branch if not (must be hard error!) 

(Now write the block Just read 

(Branch on error 

(Bump Block t 

tWe could do some more processing here 

(Wait for write to finish 

(Branch if write was successful 

(RO => Write error msa 

(Report error 

(Merge to exit program 

(RO => Read error msa 

(Branch to report error 

fReaii error... EOF? 

(Branch if not 

(Yes. . .announce completion 

(Make output file permanent 

(Dismiss fetched handlers 

(then exit program 

(EMT Area block 

(Block *, 

BUFF (Buffer addr i word count 

254. (alreadB fixed in block... 

! 

256. (I/O buffer 

0,0,0,0 (No default extensions for CSIGEN 

/I-O Transfer Complete/ (Messages... 

<12><15>/< Simulating Mainline Processing >■/ 

/?Write Error?/ 

/?Re3d Error?/ 



(Handlers maa be loaded starting here 



to 

1» 
•WERR,RO 

7$ 

*RERR,RO 

4* 

e^ERRBYT 

5* 

*DONE 

*0 



.END 



START 



Programmed Request Description and Examples 2-97 



.READC 

The .READC request transfers a specified number of words from the indicated 
channel to memory. Control returns to the user program immediately after 
the .READC is initiated. Attempting to read past end-of-file also causes an 
immediate return, in this case with the carry bit set and the error byte set to 
0. Execution of the user program continues until the .READC is complete, 
then control passes to the routine specified in the request. When an RTS PC is 
executed in the completion routine, control returns to the user program. 

Macro Call: .READC area, chan, buf, went, crtn,blk 



where: 



area is the address of a five-word EMT argument block 
chan is a channel number in the range 0-377 (octal) 
buf is the address of the buffer to receive the data read 
is the number of words to be read 



went 
crtn 

blk 



is the address of the user's completion routine. The address of 
the completion routine must be above 500 (octal) 

is the block number to be read. For a file-structured .LOOKUP, 
the block number is relative to the start of the file. For a non- 
file-structured .LOOKUP, the block number is the absolute 
block number on the device. The user program normally updates 
blk before it is used again 

When a completion routine is called, error or end-of-file information for a 
channel is not cleared. The next .WAIT or .READ/.READC on the channel 
(from either mainline code or a completion routine) produces an immediate 
return with the C bit set and the error code in byte 52. The completion routine 
will never be entered if the .READC request returns an error. 



Request Format: 


RO -► area: 


10 chan 




blk 




buf 




went 




crtn 



When a .READC completion routine is entered, the following conditions are 
true: 

1. RO contains the contents of the channel status word for the opera- 
tion. If bit of RO is set, a hardware error occurred during the 
transfer; consequently, the data may not be reliable. The end-of-file 
bit may be set. 

2, Rl contains the cViannel number of the operation. This is useful 
when the same completion routine is to be used for several different 
transfers. 
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4. 



On a file-structured transfer, a shortened read is reported when the 
.READC request is returned, not when the completion routine is 
called. 

Registers RO and Rl can be used by the routine, but all other regis- 
ters must be saved and restored. Data cannot be passed between the 
main program and completion routines in any register or on the 
stack. 



Errors: 






■ 'i;^iMirtiiai ■,■■■■■ 



Attempt to read past end-of-file; no data was read. 

1 Hard error occurred on channel. 



Channel is not open. 



Example: 



.TITLE READC. MAC 

.READC / .URITC - This is en example in the use of the .READC / .URITC 
reauests. The exaniFle demonstrates event-driven I/O where s mainline 
program initiates a file transfer and completion routines continue it 
while the mainline proceeds with other processes. The example is another 
single file copy progrsmi utilizing .CSIGEN to input the file specst load 
the reouired handlers and open the files. 



JError Byte location in SYSCOM 

(Use CSIGEN to Set hsndlersr files 

(Start I/O 

jNow simulste other mainline process 





.MCALL 


.READCj .URITC, .CLO 




ERRBYT 


= 52 




.ENABL 


LSE 


start: 


.CSIGEN 


*DSPACE.*DEFEXT 




CALL 


IOXFER 




•PRINT 


*MESS6^ 




Moy 


*-lrR5 


1$: 


DEC 


R5 




BNE 


1$ 




TSTE 


EOF 




BEQ 


1* 




INCB 


EOF 




BEQ 


UERR 




BLT 


RERR 




.CLOSE 


*0 




MOV 


♦DONE.RO 




BR 


GBYE 


uerr: 


MOV 


♦URERRjRO 




BR 


GBYE 


RERR! 


MOV 


♦RDERR.RO 


GBYEt 


.PRINT 

•SRESET 

.EXIT 




urdone: 


.UAIT 


*0 




BCS 


3t 


ioxfer: 


.READC 


«AREA,*3, ,,t4» 




BCC 


7t 




TSTB 


etERRBYT 




BEQ 


6i 


2»: 


DECB 


EOF 


3*: 


DECE 
RETURN 


EOF 


At: 


• WAIT 


t3 




BCS 


2« 




.URITC 


tAREAf*0,> >*URDONE 




BCS 


3* 


5*: 


INC 
RETURN 


BLOK 


6»: 


INCB 


EOF 



! (kill some time) 

f 

JDid I/O complete? 

>No...do some more mainline work 

rCheck for read/write error 

jEOF = = Urite error 

JEOF < = Read error 

JEOF > = End of File 

!R0 => We're done messa 

fMerae to exit program 

JSet UP error messages here... 



fPrint messase 

(Dismiss fetched handlers 

(Exit proSram 

iUrite compl rtne... write successful? 

jBranch if not . . . 

iQueue up a read 

(Branch if ok. . . 

(Error - is it EOF? 

(Branch if ses 

(Use EOF Flas to indicate hard error 

(EOF = -2 Read err / = -1 Urite err 

(Leave completion code 

(Compl rtne #2 - was read ok? 

(Branch if not 

(Queue up a write... 

(Branch if error 

(Bump block * for next read 

(Leave Completion code... 

(Set EOF flas 
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7$: 


return 




area: : 


.WORD 





blok: 


.UORD 







.UORIi 


BUFF 




.UORD 


256. 




.WORD 





buff: 


• BLKU 


256. 


riEFEXTJ 


.UORD 


OiOf OfO 


done: 


.ASCIZ 


/I-O Tr 


messg: 


.ASCIZ 


/< Sirou 


uirerr: 


.ASCIZ 


/?Urite 


rderr: 


.ASCIZ 


/TReed 1 


EOF: 


.BYTE 

.EVEN 





DSPACE 


= , 





(then return 

jEMT Ares block 

J Block *i 

(Buffer sddr i word count 

(alresdu fixed in block... 

rConiF-letion rtne sddr 

SI/0 buffer 

!No default extensions for CSIGEN 
ansfer Complete/ JMessaSes... 
IstinS Msinline F'rocessina >/ 

Error?/ 
Error?/ 

(EOF fl33 

(Handlers may be loaded starting here 



.END 



START 



( + 



MTXAMP.MAC - The following is an example prosram that 
demonstrates the use of all the Hul t i-terminal 
pros rammed reauests. The program attaches all the 
terminals on 3 given sastenu then precedes with an 
input/echo exercise ora all attached terfiinels until 
double CTRL/C is sent to it. 



.MCALL 


.MTATCH, 


1 , MTPRNT > 


■ .MTC 


iET 


, .MTINf .MTOUT 


.MCALL 


.PRINT, 


.MTRCTO, , 


.MTSET. 


.MTSTATr .EXIT 


HNGUP* 


^- 4000 








(Terminal offline bit 


TTSPC* 


= 10000 








(Special mode bit 


TTLCt 


= 40000 








(Lower case mode bit 


AS.INP 


= 40000 








(Input available bit 


M.TSTS 


= 








(Teriiinal status word 


M.TSTU 


= 7 








(Terminal state byte 


M.NLUN 


= 4 








(* of LUNs word 


MTXAHP! 










(Start of program 




.MTSTAT 


*MTA.*MSTftT 




(Get MTTY status 




MOV 


MSTAT+M, 


,LUN, 


.R4 


(R4 = * LUNs 




BEQ 


MERR 






(None? Not MTTY! ! ! 




CLR 


Rl 






(Initial LUN = 




KOV 


♦AST.R2 






(R2 -> AST word array 


10$: 


.MTATCH 


♦MTA.R2. 


.Rl 




(Attach terminal 




BCC 


20* 






(Success ! 




CLRB 


TAI(Rl) 






(Set attach failed 




BR 


30t 






(Proceed with next LUN 


20* : 


HOVB 


*1,TAI(R1) 




(Attach successful 




MOV 


RliR3 






(Copy LUN 




ASL 


R3 






(Multiply by 8 for offset 




ASL 


R3 






(To the terminal status 




ASL 


R3 






(block.. . 




ADD 


*TSBfR3 






(R3 -> LUN's TSB 




.MTGET 


♦MTA.R3, 


.Rl 




(Get LUN's status 




BIS 


*TTSPC*+TTLC*. 


M.TSTS(R3) (Set special 












(mode and lower case 




.HTSET 


*nTA,R3i 


.Rl 




(Set LUN'i. iitatub. 




BITE 


*HN6UP»/400, 


.M. 


TSTU(R3) (Online? 




BNE 


30$ 






(Nope! 




.HTRCTO 


♦MTAtRI 






(Reset CTRL/0 




.MTPRNT 


♦MTA.tHELLO. 


.Rl 


(Say hello... 


30t: 


ADD 


*27R2 






(R2 -> Next AST word 




INC 


Rl 






(Get next LUN 




CMP 


R1jR4 






(Done? 




BLO 


10$ 






(NopBf go attach another 



loop; 



10$: 



CLR 

MOV 

TSTB 

BEQ 

BIT 

BEQ 

.MTIN 

BCS 



(Input i echo forever 
(until '^C"C*.. 
(Initial LUN = 
(R2 -> AST words 
(Terminal attached? 
(Nope . . . 
(Any input? 
(Nope. . 1 

♦MTAj*MTCHARiR1i*1 (Input 3 character 
ERR (Ooops! Error on input 



Rl 

*ASTiR2 

TAKRl) 

20$ 

*AS,INP»(R2> 

20$ 



.MTOUT *MTAf*MTCHAR>RlT*l (Echo the character 
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ECS 


ERR 




SOoof's! Error on output 


20t: 


ADD 


*2rR2 




iPoint to neat AST word 




INC 


Rl 




fGet next LUN 




CMP 


RlfRI 




(Done them 3ll? 




BLO 


10$ 




fNot do check another 




BR 


LOOP 




lYesj repeat (forever!) 


err: 


.PRINT 
.EXIT 


♦UNEXP 




jUnexF-ected error... 
(Print nesssSe i exit! 


MERR! 


.PRINT 
.EXIT 


♦NOMTTY 




rNot multi-terminsl 
(Print message i exit 


AST! 


.ELKU 


16. 




i Asynchronous Terminal 
-Status Uords (1/LUN) 


TAi: 


.ELKB 


16. 




jTerminal attached list 
;i Bate per LUN. , . 
to = Not attatched 


mstat: 


• BLKU 


8. 




;MTTY status block 


tsb: 


.BLKU 


16. *4. 




JTERMINAL STATUS BLOCKS 16 


mta: 


.BLKU 


4 




5EMT argument block 


MTCHAR! 


.BYTE 







i Character stored here 


hello: 


.ASCIZ 


/Hello! 


Characters tyr-ed will be echoed/ 


nomtty: 


.ASCIZ 


/?Not Multi- 


terminal system'?/ 


unexp: 


.ASCIZ 


/'''IJriexpec ted 


er ror . . . proSram aborting?/ 




.END 


MTXAMP 




jEnd of program 
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.READW 

The .READW request transfers a specified number of words from the indi- 
cated channel to memory. When the .READW is complete and/or an error is 
detected, control returns to the user program. 

Macro Call: .READW area, chan,buf, went, blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-377 (octal) 

buf is the address of the buffer to receive the data read 

went is the number of words to be read; each .READ request can 
transfer a maximum of 32K words 

blk is the block number to be read. For a file-structured .LOOKUP, 
the block number is relative to the start of the file. For a non- 
file-structured .LOOKUP, the block number is the absolute 
block number on the device. The user program normally updates 
blk before it is used again 

Request Format: 

RO -» area: 



10 


chan 


blk 


buf 


went 






If no error occurred, the data is in memory at the specified address. In an FB 
environment, the other job can be run while the issuing job is waiting for the 
I/O to complete. 
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Errors: 



Code Explanation 

Attempt to read past end-of-file. 

1 Hard error occurred on channel. 



Channel is not open. 



Example: 



•TITLE READU.MAC 

^ 

.READW / WRITU - This is 3n eKsmple in the use of the .READU / URITU 
reouests. The example is 3 single file copy proarsin. The file specs 
sre input from the console terninslj and the input % output files opened 
via the Senersl mode of the CSI. The file is copied usinS sanehronous 
I/0» and the output file is made permanent via the .CLOSE reouest. 

.MCALL .CSI GEN » . READW f . PRINT j . EXIT i .WRITW. . CLOSE. . SRESET 



ERRBYT=52 



Error Byte Loacation 



START! 


.CSIGEN 


*DSPACEr*DEXT 


SGet string from terminal 






CLR 


lOBLK 






T Input block * starts with 






MOV 


4AREA> 


R5 




;R5 => EMT Argument list 




read: 


.READU 
BCC 


R5,*3 
2* 






jRead a block on Channel 3 
;Blk*T Buff addr 8 UC already 
rEranch if no errors 


in arg blk! 




TSTB 


e«ERRBYT 




jls error EOF? 






6EQ 


3$ 






iYes.. . 






MOV 


*RERR) 


RO 




jRO => Read Error Message 




i>: 


.PRINT 
BR 


4* 






fPrint the message 
fExit program 




2«! 


.URITU 


R5r*0 






rUrite the block Just reed 






INC 


lOBLK 






JBump block * (doesn't affect 


C bit) 




BCC 


READ 






JBranch if no error 






MOV 


tUERR> 


RO 




jRO => Urite error message 






BR 


It 






.Branch to output the message 




3$: 


.CLOSE 
.PRINT 


*0 
♦ DONE 






iEnd-of-File. . . CLose output ch 
.Announce successful copy 


annel 


4»: 


.SRESET 








.Release handler<s) from memory 




• EXIT 








.Exit the program 




dext: 


.WORD 


OfOiOi 







jNo default entensians 




area; 


.WORD 









!EMT Argument block 




lOBLKJ 


.WORD 
. UORD 
.WORD 
.WORD 




BUFFR 
256. 







.Block * 

iI/0 Buffer addr 

jWord Count 




buffr: 


.BLKU 


256. 






iI/0 Buffer 




rerr: 


.ASCIZ 


/? Read 


error 


?/ 




WERR*. 


.ASCIZ 


/? Urn 


te 


error 


?/ 




done: 


.ASCIZ 


/I-O Transfer 


Complete/ 






.EVEN 












DSPACE= 


, 








»Handler(s) can be loaded starting here 



.END 



START 



2.64 .RELEAS 

(See .FETCH programmed request.) 



2-102 Programmed Request Description and Examples 



2.65 .RENAME 



The .RENAME request changes the name of the file specified and gives that 
file the current date in its directory entry. An error occurs if the channel 
specified is already open. 

Macro Call: .RENAME area,chan,dblk 
where: 

area is the address of a two-word EMT argument block 

chan is a channel number in the range 0-377 (octal) 

dblk is the address of a block that specifies the file to be renamed 
followed by the new file name 

Request Format: 
RO — * area: 



'■VlflT 



dblk 



The dblk argument consists of two consecutive Radix-50 device and file speci- 
fications. For example: 



DBLK 



.RENAME 


*AREA .«7 


,«DBLK 


SlJSE CHANNEL 


3CB 


RNMERR 




;not found 


, RAD50 


/DT3/ 






.RAD50 


/OLDFIL/ 






. RAD50 


/MAC/ 






. RAD50 


/DT3/ 






. RAD50 


/■ w E W F I L / 






.RAD50 


/MAC/ 







The first string represents the file to be renamed and the device where it is 
stored. The second represents the new file name. If a file with the same name 
as the new file name specified already exists on the indicated device, it is 
deleted. The second occurrence of the device name DT3 is necessary for 
proper operation and should not be omitted. The specified channel is left 
inactive when the .RENAME is complete. .RENAME requires that the han- 
dler to be used be resident at the time the .RENAME request is made. If it is 
not, a monitor error occurs. Note that .RENAME is legal only on files on 
block-replaceable devices (disks and DECtape). In magtape operations, the 
handler returns an illegal operation code in byte 52 if a .RENAME request is 
attempted. A .RENAME request to other devices is ignored. 

Files may not be protected or unprotected using the .RENAME request. To 
change the protection status of a file, use the PROTECT/NOPROTECT op- 
tion of the RENAME command. 
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Errors: 



Code 

Channel open. 

1 File not found. 



2 
3 

Example: 



Explanation 



Invalid operation. 

A file by that name already exists and is protected. 
A RENAME was not done. 



.TITLE RENAME. MAC 



• RENAME - This is sn eKBiriple in the use of the .RENAME reouest. 
The example rensmes 3 file according to filespecs input thru the 
.CSISPC reouest. 



start: 



i»: 

2»: 

3»: 
5$: 

area: 

defext: 

nofil: 

ILLOF-: 

nohan: 

FILESP! 
HANLOD 



.MCALL 
.HCALL 

ERRBYT 

.CSISPC 

.FETCH 

BCS 

MOV 

MOV 

MOV 

.REPT 

MOV 

.ENDR 

.RENAME 

BCC 

DECB 

BEG) 

MOV 

BR 

.SRESET 

.EXIT 

MOV 

BR 

MOV 

.PRINT 

BR 

.BLKW 

.WORD 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.BLKW 

.END 



.RENAME».PRINTf.EXIT 
.CSISPC. .FETCH, .SRESET 



♦FILESP, *DEFEXT 

♦HANLOD, tFILESP 

2$ 

♦FILESP, R2 

♦FILESP+46,R3 

eR2,FILESP+36 

4 

(R2)+,(R3)+ 

♦AREA,^0,^FILESP+36 

1* 

e+ERRBYT 

3* 

♦ILLOP,RO 

5* 



♦NOHAN, RO 
5* 
♦NOFIL, RO 

if 

5 

0,0,0,0 

/?File not found?/ 

/?Ille33l Operation?/ 

/?. FETCH Failed?/ 

39. 

START 



jError byte location 

jUse .CSISPC to set file specs 
fGet Handler from outspec 
JBranch if failed 
SR2 => Outspec 
JR3 => Inspec 

JCopB device spec to inspec 
fCopy outspec behind inspec 
jfor .RENAME... 

^Renane input file 
JOperation successful 
JMake error code -1,0 or +1 
JBranch if File-Not-Found 
illleSal operation-set up mss 
?Branch to report error 
SDismiss handlers 
JExit proSram 

JFetch failed-set up messasle 
JBranch to report error 
?File not found-setup message 
jPrint error messase 
Mhen exit via .SRESET 
fEMT Argument block 
jNo default extensions 
jError messaae text 



jCSISPC Input Area 
jHandlers can load here... 



2.66 .REOPEN 



The .REOPEN request associates the channel that was specified with a file on 
which a .SAVESTATUS was performed. The .SAVESTATUS/.REOPEN 
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combination is useful when a large number of files must be operated on at one 
time. As many files as are needed can be opened with .LOOKUP, and their 
status preserved with .SAVESTATUS. When data is required from a file, a 
.REOPEN enables the program to read from the file. The .REOPEN need not 
be done on the same channel as the original .LOOKUP and .SAVESTATUS. 

Macro Call: .REOPEN area,chan,cblk 

where: 

area is the address of a two-word EMT argument block 
chan is a channel number in the range 0-377 (octal) 

cblk is the address of the five-word block where the channel status 
information was stored 

Request Format: 



RO -► area: 


6 chan 






cblk 




Errors: 

Code 




Explanation 



The specified channel is in use. The .REOPEN has not been 
done. 

Example: 

Refer to the example for the .SAVESTATUS request. 



2.67 .RSUM (FB and XM Only) 

(See .SPND programmed request.) 

2.68 .SAVESTATUS 

The .SAVESTATUS request stores five words of channel status information 
into a user-specified area of memory. These words contain all the information 
RT-11 requires to completely define a file. When a .SAVESTATUS is done, 
the data words are placed in memory, the specified channel is freed, and the 
file is closed. When the saved channel data is required, the .REOPEN request 
is used. 

.SAVESTATUS can only be used if a file has been opened with .LOOKUP. If 
.ENTER was used, .SAVESTATUS is illegal and returns an error. Note that 
.SAVESTATUS is not legal for magtape or cassette files. 

The .SAVESTATUS/.REOPEN requests are used together to open many files 
on a limited number of channels or to allow all .LOOKUPs to be done at once 
to avoid USR swapping. 
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While the .SAVESTATUS/.REOPEN combination is useful, care must be 
observed when using it. In particular, the following cases should be avoided: 

1. If a .SAVESTATUS is performed and the same file is then deleted 
before it is reopened, it becomes available as an empty space that 
could be used by the .ENTER command. If this sequence occurs, 
the contents of the file supposedly saved changes. 

2. Although the device handler for the required peripheral need not be 
in memory for execution of a .REOPEN, the handler must be in 
memory when a .READ or .WRITE is executed, or a fatal error is 
generated. 

One of the more common uses of .SAVESTATUS and .REOPEN is to consoli- 
date all directory access motion and code at one place in the program. All files 
necessary are opened and their status saved, then they are re-opened one at a 
time as needed. USR swapping can be minimized by locking in the USR, 
doing .LOOKUP requests as needed, using .SAVESTATUS to save the file 
data, and then unlocking the USR. The user should be aware of the conse- 
quences of locking in the USR in a foreground/background environment. If the 
background job locks in the USR when the foreground job requires it, the 
foreground job is delayed until the background job unlocks the USR. 

Macro Call: .SAVESTATUS area,chan,cblk 



where: 



area is the address of a two-word EMT argument block 

chan is a channel number in the range 0-377 (octal) 

cblk is the address of the five-word user memory block where the 
channel status information is to be stored 



Request Format: 
RO -♦ area: 



chan 



cblk 



Errors: 



Code Explanation 

The channel specified is not currently associated with any files; 
that is, a previous .LOOKUP on the channel was never done. 

1 The file was opened with an .ENTER request, or a .SAVE- 
STATUS request was performed for a magtape or cassette file. 



Example: 



.TITLE SAyEST.MAC 

.SAVESTATUS / .REOPEN - This is sn example in the use of the .SAVESTATUS 
/ .REOPEN reouests. These reouests ars isost coimiiorily used together to 
consolidate access to the USR at one place in the program or if the 
program roust access more files than there are I/O channels available. 
Once a channel has been openedi its status maa he saved; to be re-opened 
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> and used later as needed. This example merges 2-6 files 
J-resdina all input files on one channel. 

•MCALL .CSIGENr . SAMESTATUS j .REOPENj .CLOSE. .EXIT 

.MCALL .READU. . HRITWj . PRINT. .PURGE 



into 1 file> 



start: 



1*: 



2»J 

4»: 



5$: 



6i', 



7«: 

8$: 
9$: 

area: 
blk: 
wblk: 
samblk; 

DEFEXT! 

noinp: 
uerr: 
rerr: 
done: 

buffr: 

nSPACE 



errbyt 

.CSIGEN 

HOV 

HOV 

Moy 

.SAVEST 

BCS 

ADD 

INC 

CHP 

BGE 

Moy 

BEG 

.REOPEN 
CLR 
.READU 
BCC 
TSTB 
BNE 

.PURGE 
ADD 
TST 
BNE 

.CLOSE 
.PRINT 
.EXIT 
.URITU 
INC 
INC 
BCC 
MOV 
BR 
MOV 
BR 
MOV 

.PRINT 
.EXIT 
.BLKU 
.UORD 
.UORD 
; .BLKW 
.UORD 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.EVEN 
.BLKU 



.END 



= 52 lError bate loc in SYSCOM 

*DSPACEj*DEFEXT JGet file specs jopen filesjload handlers 

*3iR4 JR4 = 1st input channel 

*AftEAjR3 iR3 => EMT Araument block 

*SAVBLKjR5 ;R5 => Channel saveststus blocks 

R3jR4»R5 jSave channel status 

2$ iBranch if channel never opened 

#12»R5 JAdJust R5 to point to next status block 

R4 iBump R4 to = next input channel 

#8.iR4 ?Done all input channsis? 

1* j Branch if not 

♦SAVBLK.R5 »R5 => to 1st saved channel status 

7» jBranch if no input files 

R3j*3>R5 »Re-open input channel on Ch 3 

BLK JStart readina with block 

R3r*3j*BUFFRj*256. »BLK jRead a block 

6$ {Branch if no error 

etERRBYT (Check if error = EOF 

8* {Branch if not EOF 

#3 fClear input channel for re-use 

♦ 12JR5 fPoint R5 to ne>4t saved ch status 

eR5 iAny more input channels? 

4$ {Branch if «es 

to (We're done... close output channel 

4D0NE {Announce merae complete 

{Exit proaram 
R3i»0.*BUFFR»*256. .UBLK {Urite block Just read 



{Bu«p to next output block 

{same for input blk (doesn't affect C bit) 

{Branch if no error on write 

{Write error - RO => messaae 

{ merae . . . 

(RO => No input files message 

{nerae. . . 

{RO => Read error msa 

{Report error 

{then exit proaram 

{EMT Araument block 

(Current read block 

(Current write block 

{Saved channel status area 

(No default extensions for CSIGEN 
/?No input files?/ (Error messaSes 
/?Urite Error?/ 
/?Re3d Error?/ 
/I-O Transfer Completed/ 



UBLK 

BLK 

5* 

*UERR>RO 

9* 

♦NOINP. RO 

9* 

♦RERR.RO 



5 





30. 

0.0.0.0 



256. 



START 



(I/O buffer 
iHandler* st^rt here. 



2.69 -SCCA 

The .SCCA request: 

1. Inhibits a CTRL/C abort 

2. Indicates when a double CTRL/C is initiated at the keyboard 

3. Distinguishes between single and double CTRL/C commands 
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CTRL/C characters are placed in the input ring buffer and are treated as 
normal control characters without specific system functions. The request re- 
quires a terminal status word address that is used to report consecutive 
CTRL/C input sequences. Bit 15 of the status word is set when consecutive 
CTRL/C characters are detected. The program must clear the bit. 

There are three cautions to observe when using .SCCA. First, the request can 
cause CTRL/C to appear in the terminal input stream, and therefore the 
program must provide a way to handle it. Second, the request makes it impos- 
sible to terminate program loops from the console, and therefore it should be 
used only in thoroughly tested, reliable programs. When .SCCA is in effect 
and the program enters an interminable loop, the system must be halted and 
re-bootstrapped. Third, a CTRL/C from indirect command files is not inter- 
cepted by the .SCCA request. 

A .SCCA request with a status word address of zero disables the intercept and 
re-enables CTRL/C system action. 

Macro Call: .SCCA area,addr 

where: 

area is the address of a two-word parameter block 

addr is the address of a terminal status word (an address of re- 
enables the CTRL/C command) 



Request Format: 
RO ^ area: 



35 



addr 



Errors: 

None. 
Example: 



.TITLE SCCA. MAC 



•SCCA - This is an exsKfJe in the use of the .SCCA reoiiest. The 
exairple is 3 simulation of a mainline Foreground proSrani which is 
currently suspended wsitinS for s nesssse fron the BsckSroundt but which 
needs to close 3 file (perhsps opened b« 3 .ENTER ?) before sbortina 
frOB CTRL-C action. A coxpletion routine periodicsllu inspects the CTRL-C 
status word and resumes the mainline if double CTRL-C is entered. 
NOTE. This example HUST be run as a FS Job under an FB monitor. 



.MCALL . SCCA J .RCVDCt .EXIT. .PRINT? .MRKT 

.MCALL .QSETf.SPNDr .RSUM 

start; .QSET *QELEM»*1 JAllocate another Q-Element 

.SCCA *HAREAj*SCCA J Inhibit "C"C action ba monitor 

1«J CALL CUATCH JStart "watchdoS* completion rtne 

.RCVDC *HAREAr*h6UFFr*40.>tMESG rLook for a message 

r . tNo errors - there's alwsas BG 

i . fOther processina herssi. 



•PRINT 
.SPND 



♦SLEEP 



.Announce we're soins to suspend 
.Suspend to wait for message 
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CUATCH! 

hesg: 

MARK! 

close: 



QELEMS 
MBUFFJ 

marea: 
carea: 
time: 
scca: 

abort: 

SLEEPS 



TST 
BNE 



SCCA 
CLOSE 



<proces5 nesssse here> 



BR 

TST 

BEQ 

.RSUM 

RETURN 

.MRKT 

RETURN 



i« 



SCCA 
MARK 



#CAREAf#TIMEr*CWATCH»*l 



.PRINT »ABORT 

r * 

i <Output file(s> closed hereJ 

f * 

.EXIT 



.BLKU 
.BLKU 
.BLKU 
.BLKU 
.UORD 
.UORIl 



7 

41. 

5 

4 

0j600. 





fUe've been .RSUMed. . . "C"C hit?? 

{Branch if yes 

Jotherwise assume raessaSe came in. 



i Loop. . . 

jCheck if "C"C entered... 

j Branch if no 

jYes..»u3ke Uf the mainline 

ithen leave completion code 

{Schedule to run aaain in 10 sec. 

{then leave completion code 

{Announce we're aborting 
{proceed with "orderla' abort 



jE]-!it the proaram 

{EKtra Q-Element 

jMessase buffer 

{EMT Araument blocks 

{ 

{Time out in 10 seconds 

(~C"C Status word 



.ASCIZ /?! Abort Acknowledged. 
.ASCIZ /! Mainline Suspending 



.Closins Output File(s) ! ?/ 



!/ 



.END 



START 



2.70 .SDAT/.SDATC/.SDATW (FB and XM Only) 

The .SDAT/.SDATC/.SDATW requests are used with the .RCVD/ 
.RCVDW/.RCVDC calls to allow message transfers between a foreground job 
and a background job under the FB or XM monitors. .SDAT transfers can be 
considered as similar to .WRITE requests, where data transfer is not to a 
peripheral but from one job to another. Additional I/O queue elements should 
be allocated for buffered I/O operations in .SDAT and .SDATC requests (see 
.QSET). 

Message handling in the FB monitor does not check for a word count of zero 
before queuing a send or receive data request. Since RT-11 distinguishes a 
send from a receive by complementing the word count, a .SDATW of zero 
words is treated as a .RCVDW of zero words. Thus, avoid a word count of zero 
at all times when using a .SDATW request. 

.SDAT 

Macro Call: .SDAT area,buf,wcnt 



where: 



area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be trans- 
ferred 

went is the number of words to transfer 
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Request Format: 
RO ^ area: 



25 







unused 



buf 



went 



1 



Errors: 



Code Explanation 

No other job exists. 



Example: 



.SDAT/.RCVD - This is 3ri exsmple in the use of the .SDAT/.RCVD 
reouests. The eKsmple is sctuslla two froarainsf a Bscksound Job 
which sends messssesi and 3 Foreground Jobi which receives the*. 
note; Each F'Todrsn should be assembled and linked separately. 



.TITLE SHATF.MAC 



; + 

j Foresround ProSram 



.mcall .rcmhf .huaiti .print.. exit 



startf: 



.RCyD 



»AREArtMBUFF.*40. 





.PRINT 

r 


♦FGJOB 




f 

.MUAIT 


• 




TST 


MBUFF+2 




BEQ 


FEXIT 




.PRINT 


♦ FMSG 




.PRINT 


♦MBUFF+2 




BR 


STARTF 


FEXIT! 


.EXIT 




area: 


.BLKU 


5 


mbuff; 


.BLKU 


41, 




.UORD 





FGJDB! 


.ASCIZ 


/Hi - FG alive and 


FMSG! 


.ASCIZ 


/Hey BG - Got your 




.END 


MHAITF 




.TITLE 


STARTB.Miiin 



iReauest 3 messaSe up to 80 char. 

jNo error possible - always a B6 

5 

jlio some other processing 

(like announcing FG active... 



rUsit for nessage to arrive... 

(Null message? 

(Yes... exit the program 

.Announce we got the Message... 

fand echo it beck 

fLoop to get another one 

!E>:it proarsui 

!EMT Argument Block 

.Buffer - Msa length + 1 

JMake sure 80 char message ends ASCIZ 
well and waiting for a message!/ 
message it reads:/ 



? Background Program - Send e 'null' message to stop both programs 





.MCALL 


.SDAT. .MUAIT. ,G 


starts: 


CLR 


BUFF 




.GTLIN 


♦BUFF, ♦PROMT 




.SDAT 


♦AREA. ♦BUFF. ♦40 




BCS 


1* 




.MUAIT 






TST 


BUFF 




BNE 


STARTS 




.EXIT 




it: 


.PRINT 
.EXIT 


♦ NOFG 


area: 


.BLKU 


5 


buff: 


.BLKU 


40. 


promt: 


.ASCII 


/Enter message 


nofg: 


.ASCIZ 


/'No FC?/ 




.END 


MUAITB 



{Clear 1st word 

.Get something to send to FG from TTY 
.Send input as message to FG 
(Branch on error - No FG 
iUait for message to be sent 
.Sent a null message? 
iNo...loop to send another message. 
I Yes .. .exit program 
fNo FG ! 
SExit program 
»EMT Argument Block 
)Uf to SO char message 
to be sent to FG Job/<15><12>/>/--;200> 
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.SDATC 

Macro Call: .SDATC area,buf,wcnt,crtn 

where: 

area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be trans- 
ferred 

went is the number of words to transfer 

crtn is the address of the completion routine to be entered when the 
message has been transmitted 

Request Format: 

RO -♦ area: 



25 







unused 



buf 



went 



crtn 



Errors: 

Code Explanation 

No other job exists. 

Example: 

See the example following .SDATW. 

.SDATW 

Macro Call: .SDATW area,buf,wcnt 

where: 

area is the address of a five-word EMT argument block 

buf is the buffer address of the beginning of the message to be trans- 
ferred 

went is the number of words to transfer 
Request Format: 



RO -► area: 



25 







unused 



buf 



went 







Errors: 



Code Explanation 

No other job exists. 
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Example: 



f .SDATU/RCVDU - This is an example in the use of the . SCATU/.RCyDW 
J reouests. The ei-tsaple consists of two prosraiusS 3 Foreground Job 
i which creates s file and sends s messsae to 3 Background prosrsm 
I which copies the FG channel and reads s record from the file. Both 
i prosraiis must be assembled and linked separately. 
r - 

.TITLE SDATUF.MAC 
» + 

i This is the Foreground program , , , 
F - 

.MCALL .ENTER I. PRINT, .SDATW, .EXIT, .RCVDU, .CLOSE, .URITU 

;R5 => EMT argument block 

iCreate a 5 block file 

jWrite a record BG is interested in 

fBranch on error 

fSend message with info to BG 

iDo some other processing 

SUhen it's time to exit, make sure 

iBG is done with the file 

JTell user we're going b»e-bue 

jExit the program 

JPrint error message 

jthen exit 

SFile spec for .ENTER 

)EHT argument block 
JChannel * 
; Block * 
(File record 
JError message text 
iExit message 

• TITLE SriATUB.MAC 

5 This is the Background program . . . 

r -- 

.MCALL .CHCOPY,.RCVDHf.READU,.EXIT,,PRINT,.SDATW 

;R5 => EMT srg block 

iWait for message from FG 

fBranch if no FG 

SChannel # is Ist word of message 

JBraneh if FG channel not open 

JRead block which is 2nd word of msg 

SBranch if read error 

(Continue processing... 

JTell FG we're thru with file 

(Tell user we're thru 

(then exit program 

(RO => No FG error nsg 

(Branch to print msg 

(RO => FG ch not open msg 

(Branch . . . 

(RO => Read err msg 

(Print proper error msa 

(then exit. 

(EMT argument blk 

(Message buffer 

(File buffer 

cessf ul/ 

(Error messages... 



STARTF! 


MOV 


*AREA,R5 




.enter 


R5,*0,*FILE,*5 




.URITU 


R5f*0,*RECRD,#25 




BCS 


ENTERR 




•SDATU 


R5,#BUFR,*2 




.rcmdu 


R5f*BUFR,*1 




.close 


*0 




.PRINT 


♦FEXIT 




.EXIT 




enterr: 


.PRINT 
.EXIT 


♦ERMSG 


FILE! 


.RAD50 


/DK QUFILE/ 




.RAD50 


/TMP/ 


area: 


.BLKU 


5 


bufr: 


.WORD 


O 




.UORD 


4 


RECRD5 


.BLKU 


256. 


erhsg: 


.ASCIZ 


/?Enter Error?/ 


fexiti 


.ASCIZ 


/FG Job exiting/ 




.END 


STARTF 



( + 



startb: 


Moy 


*AREAfR5 




.RCVDU 


R5f*MSGf*2 




BCS 


1$ 




.CHCOPY 


R5FtOFMSG4'2 




BCS 


2$ 




.READU 


R5,*0f#EUFF,*256.,MSG+4 




BCS 

• 


3$ 




r 
.SDATU 


R5,#MSG,*1 




.PRINT 


♦BEXIT 




.EXIT 




1$: 


Moy 


#NOJOB,R0 




BR 


At 


2t! 


MOV 


*NOCH,RO 




BR 


4$ 


3$: 


MOV 


*KIiERR,RO 


4ti 


.PRINT 
.EXIT 




AREA! 


.BLKU 


5 


MSG! 


.BLKU 


3 


BUFF! 


.BLKU 


256. 


BEXIT! 


.ASCIZ 


/Channel-Record copy sue 


NO job: 


.ASCIZ 


/?No FG Job?/ 


noch: 


.ASCIZ 


/?FG channel not open?/ 


rderr: 


.ASCIZ 


/?Re3d Error?/ 




.END 


STARTE 



2.71 .SDTTM 



The .SDTTM (Set date and time) request allows your program to set the 
system date and time. 
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Macro Call: .SDTTM area,addr 



area is the address of a two-word EMT argument block 

addr is the address of a three-word block in user memory that con- 
tains the new date and time 

Request Format: 



RO ->■ area: 



40 



addr 



The first word of the three-word parameter block contains the new system 
date in internal format (see the .DATE programmed request). If this word is 
negative (represents an illegal date), the monitor ignores it. Put a negative 
value in the first word of the parameter block if you want to change only the 
system time. If the first parameter word is positive, it becomes the new system 
date. Note that the monitor does no further checking on the date word. To be 
sure of a valid system date, you must specify a value between 1 and 12 
(decimal) in the month field (bits 13-10) and a value between 1 and the 
month length in the day field (bits 9-5). Bits 14 and 15 must be zero. 

The second and third words of the parameter block are the new high-order 
and low-order time values, respectively. This value is the double-precision 
number of ticks since midnight. If the high-order time word is negative, the 
monitor ignores the new time. Put a negative value in the second word of the 
parameter block if you want to change only the system date. If the second 
parameter word is positive, the new time becomes the system time. The 
monitor does no further checking on the new time. To be sure of a valid 
system time, you must specify a legal number of ticks for the system line 
frequency. For a 60 Hz clock, the high-order time may not be larger than 117 
(octal), and if it is equal to 117, the low-order time may not be equal to or 
larger than 15000 (octal). For a 50 Hz clock, the high-order time may not be 
larger than 101 (octal), and if it is equal to 101, the low-order time may not be 
equal to or larger than 165400 (octal). 

Changing the date and/or time has no effect on any outstanding mark time or 
timed wait requests. 

Errors: 

None. 

Example: 

.TITLE SDTTM. MAC 

i + 

J .SIiDTM.MAC - This is ar, e>!3iiiple in the use of the .SUTTM reauest. 

; The BKBffiple is 3 Dsaliaht/Stsndard Tine utility - to switch the 

i current sastem tine from Standard to Daalisht or vice verssr call 

J the proaram as a subroutine at the FTOfer- entra point. 

f - 

.MCALL .SDTTM. .PRINT. .EXIT> .GTIM 
.GLOBL STD.DALITE 
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STDt 


COM 


HR 




neg 


HR+2 


DALITEJ 


.GTIM 


*AREA,*TIME 




CALL 


JADD 




.SDTTM 


*AREAf*NEMDT 




.6TIM 


*AREAr*TIME 




RETURN 




nemdt: 


.UORD 


-1 


TIME! 


.WORD 


0>0 


hr: 


.WORD 


3 




.UORD 


45700 


area: 


.WORD 


0.0 


jadd: 








MOV 


♦HR.R4 




MOM 


♦AREA»R3 




MOV 


*HRfRl 




MOV 


~<R4),R2 




ADD 


-<R3)rR2 




MOV 


-<R4) rR5 




ADC 


R5 




ADD 


-(R3)rR5 




MOV 


R2j-<R1) 




MOV 


R5.-(R1) 




RETURN 






.END 





f Switch to STD time... 
»M3ke one hr in clock ticks 
•Get the current tine 
fAdJijst +/- 1 hour 
jSet the new system time 
JForce dste rollover (if ana) 
jReturn to caller 

J. SDTTM srsuments - No new date 

>New time 

fOne hour in clock ticks (60 cacle clock!) 

5EMT Araument Block 

SDouble precision integer add 

»R4 => Low order of Sijstem ti«e + 2 

fR3 => Low order of One hour + 2 

jRl => Low order of new time 

fPut low order of 1st operand in R2 

SAdd in low order of operand #2 

jput hish order of operand *1 in R5 

jAdd in carry (no ovrflow possible !) 

SAdd in hiah order of operand *2 (ditto!) 

jStore result where wanted 

(Return to caller 



2.72 .SERR 

(See .HERR programmed request.) 

2.73 .SETTOP 

The .SETTOP request specifies a new address as a program's upper limit. 
The monitor determines whether this address is legal and whether or not a 
memory swap is necessary when the USR is required. For instance, if the 
program specified an upper limit below the start address of USR (normally 
specified in offset 266 in the resident monitor), no swapping is necessary, as 
the program does not overlay the USR. If .SETTOP from the background 
specifies a high limit greater than the address of the USR and a SET USR 
NOSWAP command has not been given, a memory swap is required. The use 
of .SETTOP in an extended memory environment is described at the end of 
this section. 

Careful use of the .SETTOP request provides a significant improvement in 
the performance of your program. An approach that is used by several of the 
system-supplied programs is as follows: 

1. A .SETTOP is done to the high limit of the code in a program before 
buffers or work areas are allocated. If the program is aborted, mini- 
mal writing of the user program to the swap blocks (SWAP.SYS) 
occurs. However, the program is allowed to be restarted success- 
fully. 

2. A user command line is now read through .CSISPC or .GTLIN. An 
appropriate USR swap address is set in location 46. Successive 
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.DSTATUS, .SETTOP, and .FETCH requests are performed to 

the USR 



TViic 






load necessary device handh 

resident as long as possible during the procedure. 






3. Buffers and work areas are allocated as needed with appropriate 
.SETTOP requests being issued to account for their size. Fre- 
quently, a .SETTOP of -2 is performed to request all available 
memory to be given to the program. This can be more useful than 
keeping the USR resident. 

4. If the process has a well-defined closing phase, another .SETTOP 
can be issued to cause the USR to become resident again to close 
files (the user should remember to set location 46 to zero if this is 
done, so that the USR again swaps in the normal area). On return 
from .SETTOP, both RO and the word in location 50 (octal) contain 
the highest memory address allocated for use. If the job requested 
an address higher than the highest address legal for the requesting 
job, the address returned is the highest legal address for the job 
rather than the requested address. 

When doing a final exit from a program, the monitor writes the 
program to the file SWAP. SYS and then reads in the KMON. A 
.SETTOP at exit time prevents the monitor from swapping out 
the program to the swap blocks (SWAP. SYS) before reading in the 
KMON, thus saving time. This procedure is especially useful on a 
diskette system when indirect command files are used to run a 
sequence of programs. 

Macro Call: .SETTOP addr 



where: 



addr is the address of the highest word of the area desired (the last 
word the program will modify, not the first word it leaves un- 
touched) 

Notes: 

1. A program should never do a .SETTOP and assume that its new upper 
limit is the address it requested. It must always examine the returned 
contents of RO or location 50 to determine its actual high address. 

2. It is imperative that the value returned in RO or location 50 be used as the 
absolute upper limit. If this value is exceeded, vital parts of the monitor 
can be destroyed. 



Errors: 



None. 



Example: 



.TITLE SETTOP. HftC 



! + 



.SETTOP - This is sn example in the use of the .SETTOP resuest. The 
exsmple tries to obtain as much menoru as possible usinS the .SETTOP 
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i reoueslF which will force the USR into 3 susppin^ node* The .LOCK reouest 
f will brina the USR into menoru (over the high 2k of our little prosrsn !) 
; and force it to remain there until sn .UNLOCK is issued. 



.MCALL 
.HCALL 



.LOCKi .UNLOCK. .LOOKUP 
.SETTOP. .PRINT, .EXIT 



start: 



2t: 
i*t 



SYSPTR=54 

.SETTOP e*SYSPTR 

.LOCK 

.LOOKUP *AREA»*0f*FILE1 



area: 

FILEl! 



FILE2t 



lmsg: 

FlFNDt 
F2FNn! 



BCC 

.PRINT 

.EXIT 

.PRINT 

MOM 

INC 

hOV 

.LOOKUP 



1« 
tLMSG 

♦FIFND 
♦AREAfRO 
SRO 
*FILE2r2(R0) 



BCS 2» 
.PRINT *F2FND 
.UNLOCK 
.EXIT 



.BLKU 

.RADSO 

.RAD50 

.RADSO 

.RADSO 

.RADSO 

. RADSO 

•ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

• END 



fPointer to besiinnin^ of RMON 

jTry to sllocste 3II of Beihorvf <up to RMON) 

ibrind USR into meaory 

JLOOKUP 3 file on channel 

i Branch if successful 

JPrint Error MesssSe 

> then exit proarsm 

J Announce our success 

iRO => EMT Argument Block 

J Increment low b«te of 1st ars (chsn *) 

JFill in pointer to new filespec 

JDo the .LOOKUP from filled in srS block 

J pointed to b« RO. 

fBrsnch on error 

»S3B ue found it 

»now release the USR 

rand eKit program 



3 

/DK/ 

/PIP / 

/SAV/ 

/DK/ 

/TECO / 

/SAM/ 

/TError on .LOOKUP?/ 

/. ..Found PIP.SAV/ 

/, . .Found TECO.SAM/ 

START 



jEMT Argument Block 

jA File we're sure to find 



JAnother file we might find 



SError nessase 



2.73.1 .SETTOP in an Extended Memory Environment 

You can enable the extended memory feature of the .SETTOP programmed 
request with the linker A^ option or the LINK command with the /XM option 
(see Chapter 11 in the RT-11 System User's Guide). The RT-11 Software 
Support Manual describes in detail the .SETTOP request in an extended 
memory environment. The .SETTOP request operates in privileged and 
virtual jobs as follows: 

Privileged Jobs 

1. A .SETTOP that requests an upper limit below the virtual high 
limit of the program will always return the virtual high limit of the 
program. The virtual high limit is the last address in the highest 
PAR that the program uses. In this case, a value can never be 
returned below the job's virtual high lim.it, 

2. A .SETTOP that requests a job's upper limit above the program's 
virtual high limit will return the highest available address as fol- 
lows: 

a. Either the address requested or SYSLOW-2 (last used address, 
SYSLOW is next address available) is returned, whichever is 
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lower. SYSLOW is defined as the start of the USR in the XM 
monitor. 

b. If the program's virtual high limit is greater than SYSLOW (the 
user program maps over the monitor or USR), the virtual high 
limit of the program will always be returned. 

Virtual Jobs 

1. As in privileged jobs, a .SETTOP request can never get less than the 
virtual high limit of the job. 

2. If a .SETTOP requests an upper limit greater than the virtual high 
limit, the following occurs: 

a. If the virtual high limit equals 177776, this value is returned 
since this is the address limit in virtual memory. Otherwise, a 
new region and window will be created. The size of the region 
and window will be determined by the argument specified to the 
.SETTOP or by the amount of extended memory that is avail- 
able, whichever value is smaller. The .SETTOP argument 
rounded to a 32-word boundary minus the high .LIMIT value for 
the program equals the size of the region and window (see the 
LINK chapter of the RT-11 System User's Guide and the RT-11 
Software Support Manual for a description of the .LIMIT direc- 
tive in extended memory). If there are no region control blocks, 
window control blocks, or extended memory available, the pro- 
gram's virtual high limit is returned. The .SETTOP request 
uses one of the region and window control blocks allocated to the 
user, thus one less block is available to the program if the linker 
A^ option is used. 

b. Additional .SETTOP requests can only remap the original win- 
dow created by the first .SETTOP. Thus, additional requests 
will return an address no higher than that established by the 
first request and no lower than the program virtual high limit. 
An additional .SETTOP request whose argument is higher than 
the first request will cause the entire first window to be mapped. 
An additional .SETTOP request whose argument specifies a 
value below the virtual high limit eliminates the region and 
window. If another .SETTOP request then follows, it may create 
a new region and window. 



2.74 .SFPA (Special Feature) 



r~l T-lT-fc A 



ine .orrA request aiiows users witn iioaimg-pomt naraware lo set trap aa- 
dresses to be entered when a floating-point exception occurs. If no user trap 
address is specified and a floating-point (FP) exception occurs, a 
?MON-F-FPU trap occurs, and the job is aborted. 



Programmed Request Description and Examples 2-117 



Macro Call: .SFPA area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of the routine to be entered when an exception 
occurs 

Request Format: 

RO -► area: 



30 



addr 



Notes: 

1. The user trap routine must save and restore any registers it uses. It exits 
with a RTI instruction. 

2. If the address argument is 0, user floating-point routines are disabled and 
the fatal ?MON-F-FPU trap error is produced by any further traps. 

3. In the FB environment, an address value of 1 indicates that the FP regis- 
ters should be switched when a context switch occurs, but no user traps 
are enabled. This allows both jobs to use the FP unit. An address of 1 to 
the SJ monitor is equivalent to an address of 0. 

4. When the user routine is activated, it is necessary to re-execute an .SFPA 
request, as the monitor disables user traps as soon as one is serviced. It 
does this to prevent a possible infinite loop from being set up by repeated 
floating-point exceptions. 

5. If the FPU is being used, the instruction STST -(SP) is executed by the 
monitor before entering the user's trap routine. Thus, the trap routine 
must pop the two status words off the stack before doing an RTI. The 
program can tell if FP hardware is available by examining the configura- 
tion word in the monitor. 

Errors: 



Example: 



.TITLE SFPA. MAC 



.SFPA - This is sn eKsmple in the use of the .SFPA reouest. This 
example is 3 skeleton F-rosrsm which demosntrstes how to set up e 
Flostins Point tr3P routine* and the minimum sction thst routine 
must take before dismissing the error trsp. 



.MCALL .SFPAj.EXIT 



SYSPTR 
CONFIG 
FPU 



54 

300 

100 



5L.OC of beginning of Monitor 
lOffset to Monitor conf isurst ion ud 
5FPU present bit 
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START? 



SFPA 



.EXIT 



fptrap: 



CKFPU! 



1$: 



MOV 

bit 

BEQ 
CMP 
RTI 
.END 



*AREA»*FPTRAP 



IMsinline proSrsiti... 

JSet UP FPU error trap 

rcontiriue msinline pro^rssi 

SExit pro^rsBi 

5FPU exception routine 
rHsndle exception... 



e*SYSPTRrRO ;R0 => bsse of RMON 
#FP11 rCONFIG(RO) JCheck for FPU hdwe 
1$ JBranch if none 

(SP)+f(SP)+ JMust POP status ress off stack! 
SBefore returnins! from interrupt 
START 



2.75 .SPCPS (FB and SM SYSGEN Option) 



The .SPCPS (save/set mainline PC and PS) request allows a program's com- 
pletion routine to change the flow of control of the mainline code. .SPCPS 
saves the mainline code PC and PS, and changes the mainline PC to a new 
value. If the mainline code is performing a monitor request, the monitor 
allows that request to finish before doing any rerouting. The actual rerouting 
is deferred until the mainline code is about to run. Therefore, the .SPCPS 
request returns an error if it is reissued before an earlier request has been 
honored. Furthermore, the data saved in the user block is not valid until the 
new mainline code is running. 

The .SPCPS request is a system generation feature and is available only in FB 
and XM. If a program issues this call under SJ or under a monitor not 
generated for the call, no action is taken and no error is returned. 

Macro Call: .SPCPS area,addr 

where: 

area is the address of a two-word EMT argument block 

addr is the address of a three-word block in user memory that con- 
tains the new mainline PC, and that is to contain the old main- 
line PC and PS 

Request Format: 

RO 



area: 



41 



addr 



Errors: 



Cude Explanatiun 

The program issued the .SPCPS call from the mainline code 
rather than a completion routine. 
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Code Explanation 

1 A previous .SPCPS request is outstanding. 

When the program issues the .SPCPS request, the monitor saves the old 
mainUne PS in the third word of the three-word block and the old mainline 
PC in the second word of the block. The monitor then changes the mainline 
PC to the contents of the first word of the block. 

Example: 



.TITLE 
.ENA5L 



SPCPS, MAC 

LC 



■SPCPS - This is an example in the use of the .SPCPS request. In this 
example .SPCPS is used to reroute the mainline code after an I/D 
error or EOF is detected by a completion routine. 

.PRINT ..CSIGEN , . EX IT . . WAl T . .SRESET 



!Error Byte location in SYSCOM 



iUsB CSIGEN to Set handlers, files 
iStart I/O 

iNow simulate other mainline process 
i (Kill some time) 

;E0F > = End of File 
;R0 -> We're done messs 
iMerSe to exit program 
iSet up error messajles here... 



1 P r i n t message 

iDismiss fetched handlers 

lExit program 

iWrite com pi rtne... write successful? 

SBranch if not... 

5 Q u e u e up a read 

iBranch if ok . . . 

iError - is it EOF? 

iBranch if "es 

iMoue Read err rtne addr to ar^ blocK 

iMe r Se . . . 

iMoue Write err rtne addr to ard blocK 

ifllready done a .SPCPS? 

J Yes... don't do another 

iDe-rail mainline code 

iFlaS ue'ue done this 

iOoops! Something's amiss! 

iLeaue completion code 

iCompl rtne fl2- was read oK'^ 

SBranch if not 

; Q u e u e up a write... 

iBranch if error 

iBump block « for next read 

iLeaue Completion code... 

iPrint .SPCPS failed messaae 



iEMT Area blocK 

! B 1 c K » I 

i B u f f e r addr & word count 

ialready fixed in block... 

! C m p 1 e t i n rtne addr 

i. SPCPS Arsumenv block (FINI default) 

i I / buffer 

iNo default extensions 

i.SPCPB called flaS in 





.MCALL 


.READC ..WRITCf.CLO 




.MCALL 


, SPCPS 




ERRBYT 


= 52 




.ENABL 


LSB 


START: 


.CSIGEN 


»DSPACE.»DEFEXT 




CALL 


lOXFER 




.PRINT 


SMESSG 


1$: 


DEC 


R5 




BR 


It 


FINI: 


.CLOSE 


»0 




MOy 


SDDNE tRO 




BR 


GBYE 


WERR: 


Moy 


• WRERR ,R0 




BR 


GBYE 


RERR: 


MOM 


SRDERR ,R0 


GBYE: 


.PRINT 

.SRESET 

.EXIT 




WROONE: 


.WAIT 


SO 




BCS 


3t 


IDXFER: 


.READC 


sAREA .»3 . . .«Bt 




BCC 


5t 




TSTB 


@»ERRBYT 




BED 


a* 


2$: 


MD1.I 


«RERR. SBLOK 




BR 


at 


3$: 


Moy 


»WERR .SBLOK 


at: 


TSTB 


SPCALL 




BNE 


5$ 




.SPCPS 


• AREA isSBLOK 




INCB 


SPCALL 




BCS 


7$ 


5$: 


RETURN 




S$: 


.WAIT 


83 




BCS 


2$ 




.WRITC 


«AREA .SO . . .sWRDDNE 




BCS 


3t 




INC 


BLOK 




RETURN 




7$: 


.PRINT 
RETURN 


sSPERR 


AREA: : 


.WORD 





BLOK: 


.WORD 







• WORD 


BUFF 




.WORD 


25B. 




.WORD 





SBLOK: 


.WORD 


FINI .0.0 


BUFF: 


.PLKW 


25G. 


DEFEXT: 


.WORD 


. , . 


SPCALL: 


.BYTE 






for CSIGEN 
case I/O error 



l(compl rtne Sets sohed. resardless!) 



2-120 Programmed Request Description and Examples 



DONE: 
MESSG 
WRERR 
RDERR 
SPERR 

DSPACE 



.NLIST BEX 
•ASCiZ /I-O 
.ASCIZ 
, ASCIZ 



.ASCIZ 
.ASCiZ 
.EM EN 

,END 



r a n 5 f e r Complete/ ; f i e 5 s a 3 e s , 
/ < S 1 m 1-1 1 a t i n 3 M a i ri 1 i n e P r c e 5 s i n s 
/ 'r' W r i t- e Error?/ 
/ ? R e a d E r r r '^ / 
/?,SPCPS Error'?/ 



i H a n d 1 e r 5 may be loaded s t a r t i r 



START 



2.76 .SPFUN 



This request is used with certain device hanalers to ao aeviceaeper 
tions, such as rewind and backspace. It can be used with diskettes and some 
disks to allow reading and writing of absolute sectors, this request can deter- 
mine the size of a volume mounted in a particular device unit for RX02 
diskettes, RK06/RK07 disks, and RLOl disks. 

Macro Call: .SPFUN area,chan,func,buf,wcnt,blk[,crtn] 

where: 

area is the address of a six-word EMT argument block 

chan is a channel number in the range to 377 (octal) 

func is the numerical code of the function to be performed; these 
codes must be negative 

buf is the buffer address; this parameter must be set to zero if no 
buffer is required 

went is defined in terms of the device handler associated with the 
specified channel and in terms of the specified special function 
code 

blk is also defined in terms of the device handler associated with the 

code 

crtn is the entry point of a completion routine. If left blank, is 
automatically inserted. This value is the same as for .READ, 
.READC, and .READW. 

= wait I/O (.READW) 

1 = real time (.READ) 

Value >500 = completion routine 
Request Format; 
RO -► area: 



32 chan 



blk 



buf 



went 



code 377 



crtn 
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The chan, blk, and went arguments are the same as those defined for 
.READ/. WRITE requests. They are only required when doing a .WRITE with 
extended record gap to magnetic tape. If the crtn argument is left blank, the 
requested operation completes before control returns to the user program. 
Specifying crtn as #1 is similar to executing a .READ or .WRITE in that the 
function is initiated and returns immediately to the user program. A .WAIT 
on the channel makes sure that the operation is completed. The crtn argu- 
ment is a completion routine address to be entered when the operation is 
complete. 

The available functions and function codes for magtape and cassette are as 
follows: 



Function 


MT 


CT 


Forward to last file 




377 


Forward to last block 




376 


Forward to next file 




375 


Forward to next block 




374 


Rewind to load point 


373 


373 


Write file gap 




372 


Write EOF 


377 




Forward one block 


376 




Backspace one block 


375 




Write 


371 




Read 


370 




Write with extended 






file gap 


374 




Off-line rewind 


372 





The available functions and function codes for diskettes, RK06/RK07 disks, 
and RLOl disks are as follows: 



Function 


DX 


DM 


DY 


DL 


Read 


377 


377 


377 


377 


Write 


376 


376 


376 


376 


Write with deleted 










data mark 


375 




375 




Force a read by the 










handler of the bad 










block replacement 










table from block 1 










of the disk 




374 




374 


Return device size 




373 


373 


373 



To use the .SPFUN request, the handler must be in memory and a channel 
must be associated with a file via a .LOOKUP request. 

A .SPFUN request to write absolute blocks on a diskette should not write 
anything in track if you want to use DUP or the COPY/DEVICE coro.mand 
to back up the volume. DUP does not copy data in track 0. Also, you should 
be careful to specify a valid buffer address and word count. The monitor 
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checks that the buf argument is in the job area, but it does not check buf + 
went. If you use the .SPFUN request, and the device handler for that device 
does not support special functions, the call simply returns to the program 
without reporting an error. 

For the RK06/07 handler (DM), special function codes 377 and 376 require the 
buffer size to be one word larger than necessary for the data. The first word of 
the buffer contains the error information returned as a result of the .SPFUN 
request. The data transferred as a result of the read or write request is found 
in the second and following words of the buffer. The error codes and informa- 
tion are as follows: 

Code Meaning 

100000 The I/O operation is successful. 
100200 A bad block was detected (BSE error). 

100001 An ECC error is corrected. 

100002 An error recovered on retry. 

100004 An error recovered through an offset retry. 

100010 An error recovered after recalib ration. 

1774xx An error did not recover. 

04-U£i« rJf^TT^^f. c-r-.or>ifi'^ ■'Tfn'»'-*>-'Qti'T*-> iG inr'lii'^pr' ii^ fV»p PT'— 7 7 ^nffM^nro Ssiirtrtnrf 

Manual. 



Errors: 



Code Explanation 

Attempt to read or write past end-of-file. 

1 Hard error occurred on channel. 

2 Channel is not open. 

Additional qualifying information for these errors is returned in the first 
two words of the blk argument status block. This information is given in 
Chapter 10 of the RT-11 Software Support Manual. 



Example: 



•TITLE SPFUN. MAC 



J .SPFUN - Thii is an e;;smple in the use of the .SPFUN reouest. The 
! exaniF-le rewinds a cassette and writes out a 256-word buffer and 
; then 3 file Sap. 



.MCALL .FETCH» . LOOKUP .. SPFUN . .WftITU 
iMCALL iEXIT; = PR INT- ,yAIT« .CLOSE 



start: .FETCH *HSPC.*CT 
BCS 1* 
.LOOKUP *AREA.*4!#CT 



;Fetch the CT Handler 

iPranch if failed 

rOpen channel 4 for output 
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1$! 

3*: 

5*{ 



BCS 

.SPFUN 

BCS 

.URITW 

BCS 

.SPFUN 

.PRINT 

.UAIT 

.CLOSE 

.EXIT 

MOM 
BR 
MOV 
BR 

Mog 

BR 
MOV 
.PRINT 
.EXIT 



2$ fBrarich if error (should never happen!) 

*AREA>*4 j*373r to JRewind to EOT using Ssnehronous I/O 

3$ fBrsnch on error 

♦AREAt*4»#BUFFi*256. fBLK JWrite one block 

4* JBrsnch on error 

»AREAf*4»*372j*0» .*1 JWrite s file Sbf with As«cnh I/O 

♦DONE ? Announce that we're done 

♦4 jWait for file ^3p operation to finish 

»4 jClose the filc^ 

;then exit the proSra* 



♦FERRjRO 

5t 

♦LKERRrRO 

5* 

♦SPERR.RO 

5* 

♦WERRrRO 



(Process errors here. 



jprint error nessa^e 
fthen exit proaram 



area: 

blk; 

ct: 

buff: 
bone: 
ferr: 

LKERRJ 

sperr: 
uerr: 



.WORD 

.word 

.RAD5 

.UORD 

.BLKW 

• ASCI 

.ASCI 

.ASCI 

.ASCI 

.ASCI 

.EVEN 

HSPC 

.END 



jEMT Arsu»ent block 



/CT / 

0»OfO 

256. 
Z /All done !/ 
Z /?. FETCH Error?/ 
Z /?. LOOKUP Error?/ 
Z /?Special Function Error?/ 
Z /?Write Error?/ 



rCassette Device Descriptor 
fNull filespec 
fOutPut buffer 
fHessaae text . . . 



JHandler can load in here... 



START 



2.77 .SPND/.RSUM (FB and XM Only) 

The .SPND/.RSUM requests control execution of a job's mainline code (the 
code that is not executing as a result of a completion routine). .SPND 
suspends the mainline and allows only completion routines (for I/O and mark 
time requests) to run. .RSUM from one of the completion routines resumes 
the mainline code. These functions enable a program to wait for a particular 
I/O or mark time request by suspending the mainline and having the selected 
event's completion routine issue a .RSUM. This differs from the .WAIT re- 
quest, which suspends the mainline until all I/O operations on a specific 
channel have completed. 



Macro Calls: 


SPND 




RSUM 


Request Formats: 


(.SPND) 


R0 = 


(.RSUM) 


R0 = 


Notes: 





1 


2 1 



1. The monitor maintains a suspension counter for each job. This counter is 
decremented by .SPND and incremented by .RSUM. A job is suspended 
only if this counter is negative. Thus, if a .RSUM is issued before a 
.SPND, the latter request returns immediately. 
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2. A program must issue an equal number of .SPND and .RSUM requests. 

3. A .RSUM request from the mainline code increments the suspension 
counter. 

4. A .SPND request from a completion routine decrements the suspension 
counter, but does not suspend the mainline. If a completion routine does a 
.SPND, the mainline continues until it also issues a .SPND, at which time 
it is suspended and requires two .RSUMs to proceed. 

5. Since a .TWAIT is simulated in the monitor using suspend and resume, a 
.RSUM issued from a completion routine without a matching .SPND can 
cause the mainline to continue past a timed wait before the entire time 
interval has elapsed. 

6. A .SPND or .RSUM, like most other programmed requests, can be issued 
from within a user-written interrupt service routine if the 
.INTEN/.SYNCH sequence is followed. All notes referring to 
.SPND/.RSUM from a completion routine also apply to this case. 



Errors: 



None. 



Example: 



.TITLE SPND. MAC 



.SPNIi/.RSUM- This is an exsuple in the use of the .SPND/.RSUN reouests. 
The exaiiPle is a sinulstion of 3 mainline Foresround proaran which is 
currently suspended usitinS for 3 nesssae from the Bsckaroundt but which 
needs to close 3 file <perh3Ps opened by 3 .ENTER ?) before aborting 
froBi CTRL-C action. A completion routine periodicsllB inspects the CTRL-C 
ststus word snd resuaes the mainline if double CTRL-C is entered. 
note; This example MUST be run as a FG Job under an FB monitor. 



START! 

1$: 



.MCALL 
.MCALL 

.QSET 
.SCCfl 
CALL 
•RCyDC 



.PRINT 
.SPNIi 
TST 
BNE 



.SCCAkRCMDCj .exit I .PRINT. .HRKT 
.QSET, .SPND,. RSUH 



*QELEMr*l ^Allocate anotner u-tiem 

»MAREA,*SCCA finhibit "C"C action by 

CUATCH jStart 'watchdoa' comple 

»«AREA,*MBUFF,*40. »*MESG ,'Look for a messaSe 
. iNo errors - there's always B6 



ent 

monitor 
tion rtne 



♦SLEEP 



SCCA 
CLOSE 



jOther processina here... 

i 

J Announce we're soina to suspend 

!Suspend to wait for messase 

JWe've been .RSUHed. . .""C'C hit?? 

•Branch if «es 

jotherwise sssume message came in. 



<process message here> 



BR 1* 



cwatch: 


TST 


SCCA 




BEQ 


MARK 


MESGt 


.RSUH 
RETURN 




mark: 


.HRKT 
RETURN 


♦ CAR 


close; 


.PRINT 


tABO 



*CAREA,*TIME,*CUATCH,*1 



<Output file(s) closed here> 



(Loop. . . 

iCheck if ~C"C entered... 
jBranch if no 

$Yes...uake up the mainline 
(then leave completion code 
^Schedule to run aSain in 10 
jthen leave completion code 



{Announce we'i 
Jproceed with 



3 abort ina 
"orderly" abort 



.EXIT 



!E:;it the proaram 
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qelem: 


.BLKU 


7 


HBUFF! 


.BLKW 


41, 


marea: 


.BLKU 


5 


carea; 


.BLKU 


4 


TIME! 


.WORD 


0,600, 


SCCA! 


.WORD 





ABORT! 


•ASCIZ 


/?! Ab 


SLEEP! 


.ASCIZ 


/! Msi 



rExtrs Q-Element 

5Messs2e buffer 

!EMT Arsument blocks 

? 

iTiine out in 10 seconds 

}"C"C Stetus word 

Ackrfouledsed. ., Closing Output FileCs) !?/ 
/! Mainline Suspending !/ 



.END START 



2.78 .SRESET 

The .SRESET (software reset) request: 

1. Cancels any messages sent by the job. 

2. Waits for all job I/O to complete, which includes waiting for all 
completion routines to run. 

3. Dismisses any device handlers that were brought into memory via 
.FETCH calls. Handlers loaded via the keyboard monitor LOAD 
command remain resident, as does the system device handler (only 
for background jobs). 

4. Purges any currently open files. Files opened for output with 
.ENTER are never made permanent. 

5. Reverts to using only 16(decimal) I/O channels. Any channels de- 
fined with .CDFN are discarded. A .CDFN must be reissued to open 
more than 16(decimal) channels after a .SRESET is performed. 

6. Clears the job's .SPND/.RSUM counter. 

7. Resets the I/O queue to one element. A .QSET request must be 
reissued to allocate extra queue elements. 

8. Cancels all outstanding .MRKT requests. 
Macro Call: .SRESET 

Errors: 

None. 
Example: 

.TITLE SRESET. MAC 

+ 
.SRESET - This is an e>;aii,fle in the use of the .SRESET reouest. 
The ex3»ple renames 3 file sccordina to filespecs input thru the 
.CSISPC reouest. 

.HCALL .RENAME,. PRINT.. EXIT 
.HCALL .CSiSFCr .FETCH , . 3RESE I 

ERRBYT = 52 lError bate location 
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START J 


.CSISPC 


•FILESP. *DEFEXT 


iUse .CSISPC to Set file specs 




.FETCH 


*HANLOIi.*FILESP 


fGet Hsndler from outspec 




BCS 


2* 


.Branch if fsiled 




Moy 


*FILESPfR2 


»R2 => Outspec 




Moy 


♦FILESF+46.R3 


jR3 => Inspec 




HOV 


eR2.FILESP+36 


JCopa device spec to inspec 




• REPT 


4 


jCopa outspec behind inspec 




MOV 


(R2)+.(R3)+ 


jfor .RENAME.., 




• ENDR 








.RENAME 


*AREA.*0.*FILESP+36 


jRensBie input file 




BCC 


1* 


fOperstion successful 




riECB 


e*ERRBYT 


jMske error code -1.0 or +1 




BEQ 


3$ 


JBrsnch if File-Not-Found 




MOV 


♦ILLOP. RO 


»Ille33l operstion-set up mss 




BR 


5* 


.Brsnch to rsport error 


1*J 


.SRESET 




SDismiss handlers 




• EXIT 




SExit proSrsm 


2t: 


MOV 


♦NOHAN. RO 


.Fetch fsiled-set up messe2e 




BR 


5* 


.Branch to report error 


3*: 


MOV 


♦NOFIL. RO 


.File not found-setup message 


5*: 


.PRINT 




.Print error message 




BR 


1» 


jThen exit via .SRESET 


area: 


.BLKU 


5 


»EMT Argument block 


DEFEXTS 


, UORIi 


0.0.0.0 


.No default extensions 


nofil; 


.ASCIZ 


/?File not found?/ 


JError message text 


illop: 


.ASCIZ 


/Tllleasl Operstion?/ 




NOHAN; 


.ASCIZ 
.EVEN 


/?. FETCH Fsiled?/ 




FILESP! 


.BLKW 


39. 


fCSISPC Input Area 


HANLOD 


= , 




.Handlers can load here... 



.END 



START 



2.79 .SYNCH (Device Handler and Interrupt Service Routine 
Only) 

This macro call enables your program to issue programmed requests from 
within an interrupt service routine. Code following the .SYNCH call runs at 
priority level as a completion routine in the issuing job's context. Pro- 
grammed requests issued from interrupt routines are not supported by the 
system and should not be performed unless a .SYNCH is used. .SYNCH, like 
.INTEN, is not an EMT monitor request, but rather a subroutine call to the 
monitor. 

Macro Call: .SYNCH area[,pic] 

where: 

area is the address of a seven-word block that you must set aside for 
use by .SYNCH. This argument, area, represents a special 
seven-word block used by .SYNCH as a queue element. This is 
not the same as the regular area argument used by many other 
programmed requests. The user must not confuse the two; he 
should set up a unique seven-word block specifically for the 
.SYNCH request. The seven-word block appears as: 

Word 1 RT-11 maintains this word; its contents should not be 
altered by the user 
2 The current job's number. This must be set up by the 
user program. It can be obtained by a .GTJB call 
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3 


Unused 


4 


Unused 


5 


RO argument. When a successful return is made from 




.SYNCH, RO contains this argument 


6 


Must be -1 


7 


Must be 



pic is an optional argument that, if non-blank, causes the .SYNCH 
macro to produce position-independent code for use by device 
drivers 



Note: 



.SYNCH assumes that the user has not pushed anything on the stack 
between the .INTEN and .SYNCH calls. This rule must be observed for 
proper operation. 



Errors: 



The monitor returns to the location immediately following the .SYNCH 
if the .SYNCH was rejected. The routine is still unable to issue pro- 
grammed requests, and R4 and R5 are available for use. An error is 
returned if another .SYNCH that specified the same seven-word block 
is still pending. 

NOTE 

The monitor dismisses the interrupt without returning to the 
.SYNCH routine if one of the following conditions occur: 

1. You specified an illegal job number. 

2. The job number does not exist (for example, you specify 2, 
and there is no foreground job). 

3. The job is exited or terminated with an .EXIT programmed 
request. 

You can find out if the block is in use by: 

i. Checking location Q.COMP (offset 14 octal). If this location con- 
tains a zero, the block is available. 

2. Performing a .SYNCH call. If the block is busy, an error return will 
be performed. 

Normal return is to the word after the error return. At this point, the 
routine is in user state and is thus allowed to issue programmed re- 
quests. RO contains the argument that was in word 5 of the block. RO 
and Rl are free for use without having to be saved. R4 and R5 are not 
free, and do not contain the same information they contained before the 
.SYNCH request. A long time can elapse before the program returns 
from a .SYNCH request since all interrupts must be serviced before the 
main program can continue. Exit from the routine should be done via 
an RTS PC. 
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Example: 



.TITLE SYNCH. HAC 



.SYNCH - This is an exsmple in the use of the .SYNCH reouest. 
The ejomple is s skeleton of s proSrasi which could input date 
froB the outside world via sn in-line interrupt service routine? 
buffer it until s whole block's worth has been inputi then use 
3 .URITE reouest to store the data on an RT-11 device. 



.hCALL 



.GTJB..INTEN. .URITE. .WAIT , . SYNCH r .EXIT. .PRINT 



»^Li£>i * n*J 



m -(»«>- u>. 



.GTJB 
MOM 



INTRPTJ 



.INTEN 



.SYNCH 

BR 

i 

.WAIT 

BCS 

.HRITE 

INC 

r 

RETURN 



♦AREA.R5 
(R5).SYNBLK+2 



iGet Job number (could be 
.Store the Job number into 
. JHere we open an RT-11 out 

. .then initiate input from 

. .device, interrupts to be 

. jin-line service routine.. 

INTERRUPT SERVICE ROUTINE 
5 jNotifu RT-11 and drop to 

. SProcess interrupt. . .buff e 

. (Time to write a buffer 

. .(should be double buffere 

. Scan continue while in WRI 

♦SYNBLK .DO A .SYNCH so we can use 

SYNFAIL JReturns here if .SYNCH bl 

. .Returns here if OK... 

*1 JSee if error on la 

HTFAIL JBranch if there w 

*AREAr*1.0BUFF.*256,.ELK fQueue up 
BLK .Bump block * 

. jRe-enable interrup 



either FG or BG) 

synch block 
put device, 
a "foreian" 
handled bu our 



Prioritu 5 
r input 

switch buffers 
d so interrupts 
TE operation ! ) 

.WRITE reouest 
ock in use 



St write 

ITE to store data 



s . . . 

a UR 



ts and leave. 



SYNBLK) 



.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 







5 
-1.0 



S. SYNCH Block 

.Job Number soes here 

fnext 2 words reserved 

r 

.RO contains 5 on successful 
jMUST BE values for Monitor 



.SYNCH 



synfail: 



wtfail: 
errh: 

blk: 

area: 

job: 

obuff: 

ibuff: 

buffi: 

BUFF2! 

werr: 
syner: 



MOV 

BR 

MOV 

•PRINT 

.EXIT 

.WORD 

.BLKW 

.FLKW 

.WORD 

.WORD 

.BLKU 

.BLKW 

.ASCIZ 

.ASCIZ 

.EVEN 



♦SYNER. RO 
ERRM 

«WERR.RO 





5 

8. 





256. 

256. 

/?Write Error?/ 

/?SYNCH Failed?/ 



i .SYNCH Failed. . . 
jRO => Error messaae 
SBranch to report error 

.\:ncfs ue iiOiii i»iuna uuiii^erti/:/ 

.RO => Write error message 

jReport error 

.Then exit 

jBlock to write 

.EMT Argument Block 

fArea for .6TJB data 

{Pointer to current output buffer 

.Pointer to current input buffer 

fBuffer *1 

JBuffer #2 



.END 



START 



2.80 .TIMIO (Device Handler Only) 

The .TIMIO macro issues the device time-out call in the handler I/O initia- 
tion section. This request schedules a completion routine to run after the 
specified time interval has elapsed. The completion routine runs in the con- 
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text of the job indicated in the timer block. In XM systems, the completion 
routine executes with kernel mapping, since it is still a part of the interrupt 
service routine. (See the RT-11 Software Support Manual for more informa- 
tion about interrupt service routines and the XM monitor.) As usual with 
completion routines, RO and Rl are available for use. When the completion 
routine is entered, RO contains the sequence number of the request that timed 
out. 

Macro Call: .TIMIO tbk,hi,lo 

where: 

tbk is the address of the timer block, a seven-word pseudo timer 
queue element. (The timer block format is shown in Table 2-1 
under the .CTIMIO request.) You must set up the address of the 
completion routine in the seventh word of the timer block in a 
position-independent manner 

hi is the high-order word of a two- word time interval 

lo is the low-order word of a two-word time interval 

Example: 



.TITLE TIMIO. MAC 



TIMIO. MAC- This is an example of 3 simplei RT-11 device driven 
to illustrate the use of the .TIMIO/. CTIMIO reouests. The tiaeout 
completion routine will be entered if 3 character hasn't been 
successfully transmitted in 1/10 sec (appro;-;. 110 bsud). In this 
example the completion routine takes no explicit action? the fact 
that the timeout occurred is enoush to be considered a "hard" error. 



■MCALL 



.DRBEGi .DRASTr .DRFlNi . DRENDf . OELDF . .TIMIO f . CTIMID 



.IIF NDF MMG*T» MMGtT=0 

.IIF NDF ERL«Gj ERLt6=0 

.IIF NDF TIM$ITf TIM$IT=0 

.IIF NDF SPJMEC. SP»yEC=304 

.IIF NDF SP»CSRr SP$CSR=176504 

.IIF NDF SPSPRIi SP*PRI=4 



SPRET! 



lOERR = 


1 


SPSTS = 


20000 


SPSIZ = 





TIME = 


6 


.QELDF 




.DRBEG 


SPrSPSVEC. SPSIZ T SPSTS 


MOM 


SPCQErR4 


ASL 


Q«UCNT(R4) 


BCC 


SPERR 


BEO 


SPDUN 


MOV 


PC»R5 


ADD 


»SPT0UT-.rR5 


MOV 


R5fTBLK+14 


.TIMIO 


TBLKiOfTIME 


BIS 


»100>e*SP$CSR 


RETURN 




UPT SERVICE ROUTINE 


.DRAST 


SP.SP»PRI 


MOV 


SPCQE,R4 


TST 


g*SP«CSR 



■Define these in case not 
^assembled with SYSCND.MAC 



rDefine default vector 
SDEfine default CSR addr 
fDefine default device priority 

fHard I/O error bit definition 
jDsvice Status = Write onlB 
(Device Size = (Char device) 
rTimeout interval = 1/10 sec 

iUse .QELDF to define Q-Elen offsets 

fBe^in driver code with .DRBEG 

jR4 => Current Q-Element 

fMake word count bate count 

>A read from a write/onlu device? 

rZero word count... Just exit 

■Calculate PIC address 

rcoapletion routine 

■Move it to araument block 

{Schedule a marktime 

(Enable DL-11 interrupt 

(Return to monitor 



(Use .DRAST to define Int Svc Sect. 

(R4 => Q-Element 

(Error? 
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BMI SPftET 

TSTB 8*SP$CSR 

BPL SPRET 

.CTIMIO TELK 

BCS SPERR 

MOVE eQtBUFF(R4)ie*SP*CSR+2 

INC Q$BUFF(R4) 

INC QtUCNT(R4) 

BEQ SPDUN 

BR SPRET 



SPTOUT! 



RETURN 

SPERR: bis *I0ERR.eG!$CSUCR4) 

spdun: .drfin sp 

TBLK: .word 0. time. OfO, 17766, -1,0 

• DRENIi SP 
.END 



J Yes. . . 'hans' until ready 

tIs device reada? 

}No...3o wait 'till it is 

iCancel completion routine 

JToo late - it timed out! 

SXfer bate from buffer to DL-li 

JBump the buffer pointer 

i and the word count (it's neaative!) 

SBranch if done 

;Go w3it 'till char Knitted 

JTimeout comFletior: routine 

fin this examplei it does nothinS. 

fin real life it may want to try 

jto take some corrective action... 

fSet error hit in CSU 

JUse .DRFIN to return to Monitor 

f.TIMIO arsuaent block 

fUse .DREND to end code 



2.81 .TLOCK 



The .TLOCK (test lock) request is used in an FB environment to attempt to 
gain ownership of the USR. It is similar to .LOCK in that, if successful, the 
user job returns with the USR in memory (it is identical to .LOCK in the SJ 
monitor). However, if a job attempts to .LOCK the USR while another job is 
using it, the requesting job is suspended until the USR is free. With .TLOCK, 
if the USR is not available, control returns immediately with the C bit set to 
indicate the .LOCK request failed. 

Macro Call: .TLOCK 

Request Format: 

R0 = 

Errors: 



Code Explanation 

USR is already in use by another job. 
Example: 

.TITLE TLOCK. MAC 



.TLOCK - This is an ejomple in the use of the .TLOCK reauest. 
In this exanplef the user prosram needs the USR for a sub-Job it is 
executing. If it fails to Set the USR it 'suspends" that sub-Job and 
runs another sub-Job (that perhaps doesn't need the USR for eKecution). 
This type of procedure is useful to schedule several sub-Jobs within 
a sinale backsround or forearound prosram. 



.MCALL . TLOCK,. LOOKUP r .UNLOCK, .EXIT, .PRINT 



start; 



.TLOCK 
BCS 



SUSPND 



SBeain Mainline proSram 

jTra to set the USR for 1st 'Job' 

fFai led. . .branch to "suspend" 1st Job 
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.LOOKUP tAF;EA>t4>*FILE > Succeeded. . .proceed with 1st Job 



BCS 



LKERR 





.print 


•JIHSG 




.UNLOCK 






TSTB 


J2SU 




BNE 


1* 




CALL 


J0B2 


l*t 


.EXIT 




SUSPND5 








TSTB 


J2SU 




BNE 


START 




JSR 


PCf J0B2 




INC 


J2SW 




BR 


START 


area: 


.BLKU 


5 


FILE? 


.RAD50 


/DK/ 




.RAII50 


/QUFILE/ 




.RADSO 


/THP/ 


LKERRI 


.PRINT 
.EXIT 


♦LKMSG 


lkhsg: 


.ASCIZ 


/?File N 


JIMSGJ 


.ASCIZ 


/Job *1 


J2MSB: 


.ASCIZ 


/Job »2 


J2su: 


.BYTE 
.EVEN 





J0B2: 


.PRINT 


*J2MS6 




RTS 


PC 



iBrsnch if error on LOOKUP 

list Job invovles file processing. . .do it! 

iTell user we executed... 

list Job finished. 4 . release USR 

jCheck if we ran Job #2 while USR busy 

> Yup - we did 

jNope - do it now 



I 'Suspend' current 'Job' 

$Did we slread'j run Job #2 

jYes - don't do it sssin 

i 'Run' other "Job" 

JSet switch thst says we ran Job #2 

iUhen it's finished^ try 1st Job 3^sin 



jEHT Braunent block 
(File spec for Job *1 



(Error on .LOOKUP 



Report it! 



(Switch to control Job *2 execution 



i2nd 'Job" - Poesn't need USR 
jReturn when done 



.END 



START 



2.82 .TRPSET 



.TRPSET allows the user job to intercept traps to 4 and 10 instead of having 
the job aborted with a ?MON-F-Trap to 4 or ?MON-F-Trap to 10 message. If 
.TRPSET is in effect when an error trap occurs, the user-specified routine is 
entered. The status of the carry bit on entry to the routine determines which 
trap occurred: carry bit clear indicates a trap to 4; carry bit set indicates a 
trap to 10. The user routine should exit with an RTI instruction. Traps to 4 
can also be caused by user stack overflow on some processors (check your 
processor handbook). These traps are not intercepted by the .TRPSET re- 
quest, but they do cause job abort and a printout of the message 
?MON-F-Stack overflow in the SJ monitor or ?MON-F-Trap to 4 in the FB 
and XM monitors (see the RT-11 System Message Manual). 

Macro Call: .TRPSET area,addr 

where: 



area is the address of a two-word EMT argument block 

addr is the address of the user's trap routine. If an address of is 
specified, trap interception is disabled 

Request Format: 

RO ->■ area: 



addr 
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Notes: 

1. Reissue a .TRPSET request whenever an error trap occurs and the user 
routine is entered. The monitor disables user trap interception prior to 
entering the user trap routine. Thus, if a trap should occur from within the 
user's trap routine, an error message is generated and the job is aborted. 
The last operation the user routine should perform before an RTI is to 
reissue the .TRPSET request. 

2. In the XM monitor, traps dispatched to a user program by .TRPSET 
execute in user mode. They appear as interrupts of the user program by a 
synchronous trap operation. Programs that intercept error traps by trying 
to steal the trap vectors must be carefully designed to handle two cases 
accurately: programs that are virtual jobs and programs that are privi- 
leged jobs. 

If the program is a virtual job, the stolen vector is in user virtual space 
that is not mapped to kernel vector space. The proper method is to use 
.TRPSET; otherwise interception attempts fail and the monitor continues 
to handle traps to 4 and 10. 

If the program is a privileged job, it is mapped to the kernel vector page. 
The user can steal the error trap vectors from the monitor, but the benefits 
of doing so must be carefully evaluated in each case. Trap routines run in 
the mapping mode specified by bits 14 and 15 of the trap vector PS word. 
With both bits set to 0, kernel mode is set. However, kernel mapping is not 
always equivalent to user mapping, particularly when extended memory is 
being used. With both PS word bits set to 1, user mode is set, and the trap 
routine executes in user mapping. 

Errors: 

None. 

Tr.vomrxl^' 

.TITLE TRPSET. MAC 

+ 
.TRPSET - This is an example in the use of the .TRPSET reouest. 
In this eK3«ple a user trap routine is set? then deliberate 
traps to 4 8 10 are caused <not vers practical but it demonstrBtes 
that .TRPSET really works!). 

.MCALL .TRPSET. .EXIT» .PRINT 

DIVZ = 67 iDivide b« zero - illegal instruction 

START? fBeSin example 

.TRPSET ♦AREA»#TRPLOC SSet up a trap routine to handle traps 

;to 4 i 10, . . 

?lllesal instruction - Trap to 10 
(Address non-existent menory - Trap to 4 
fExit proSra* 

fTrsp routine 

!C bit set = TRAP 10 

jReport Trap to 4 

jBranch to reset trap routine 

jReport trap to 10 

JReset trap routine address 
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DIVZ 






TST 


e*l<S6666 




.EXIT 




TRPLOC: 








BCS 


It 




.PRINT 


»TRP4 




BR 


2$ 


1*; 


.PRINT 


♦TRPIO 




.TRPSET 


*AREA.*TRPLOC 



2tJ RTI JSeturn to offerrdina code 

lEhT sraumerit block 
jError messages... 



AREA! 


.WORD 


0,0 


TRP4; 


.ASCIZ 


/?Tr3P to 4?/ 


TRPIO! 


.ASCIZ 


/TTrsF- to 10?/ 



.END START 



2.83 .TTYIN/.TTINR 



The requests .TTYIN and .TTINR transfer a character from the console ter- 
minal to the user program. The character thus obtained appears right-justi- 
fied (even byte) in RO. The user can cause the characters to be returned in RO 
only, or in RO and other locations. 

The expansion of .TTYIN is: 

EMT 340 
BCS .-2 

The expansion of .TTINR is: 

EMT 340 

If no characters or lines are available when an EMT 340 is executed, return is 
made with the carry bit set. The implication of these calls is that .TTYIN 
causes a tight loop waiting for a character/line to appear, while the user can 
either wait or continue processing using .TTINR. 

If the carry bit is set when execution of the .TTINR request is completed, it 
indicates that no character was available; the user has not yet typed a valid 
line. Under the FB or XM monitor, .TTINR does not return the carry bit set 
unless bit 6 of the Job Status Word (JSW) was on when the request was 
issued. 

There are two modes of doing console terminal input. The choice is governed 
by bit 12 of the job status word. If bit 12 is 0, normal I/O is performed. In this 
mode, the following conditions apply: 

1. The monitor echoes all characters typed. 

2. CTRL/1j and the DELETE key perform line deletion and character 
deletion, respectively. 

3. A carriage return, line feed, CTRL/Z, or CTRL/C must be struck 
before characters on the current line are available to the program. 
When one of these is typed, characters on the line typed are passed 
one by one to the user program. 

If bit 12 is 1, the console is in special mode. The effects are: 

1. The monitor does not echo characters typed except for CTRL/C and 
CTRL/0. 

2. CTRL/U and the DELETE key do not perform special functions. 

3. Characters are immediately available to the program. 
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In special mode, the user program must echo the characters received. How- 
ever, CTRL/C and CTRL/0 are acted on by the monitor in the usual way. Bit 
12 in the JSW must be set by the user program. This bit is cleared when the 
program terminates. 

Regardless of the setting of bit 12, when a carriage return is entered, both 
carriage return and line feed characters are passed to the program; if bit 12 is 
0, these characters will be echoed. 

Lower-case conversion is determined by the setting of bit 14 in the JSW. If bit 

1A ;„ A 1 „i .«„*-„ „„ A„j i„ i,„j? u„: 1 ] 

x-* la \j, iuwci-tjasc ciiaiacicis aic cuiivcitcu tu upjjci-'jasc ueiuic uciiig cciiucu 

(if bit 12 is 0) and passed to a program; if bit 14 is 1, lower-case characters are 
echoed (if bit 12 is 0) and passed as received. Bit 14 is cleared when the 
program terminates. 

CTRL/F and CTRL/B (and CTRL/X in system job monitors) are not affected 
by the setting of bit 12. The monitor always acts on these characters (unless 
the SET TT NOFB command is issued). 

CTRL/S and CTRL/Q are intercepted by the monitor (unless, under the FB or 
XM monitor, the SET TT NOPAGE command is issued). 

Under the FB or XM monitor, if a terminal input request is made and no 
character is available, job execution is blocked until a character is ready. This 
is true for both .TTYIN and .TTINR, and for both normal and special modes. 
If a program requires execution to continue and the carry bit to be returned, it 
must set bit 6 of the Job Status Word before the .TTINR request. Bit 6 is 
cleared when a program terminates. 

NOTE 

The .TTYIN request does not get characters from indirect files. 
If this function is desired, the .GTLIN request must be used. 

Macro Calls: .TTYIN char 
.TTINR 



where: 



char is a pointer to the location where the character in RO is to be 
stored. If char is specified, the character is in RO and the address 
is pointed to by char. If char is not specified, the character is in 
RO 

Errors: 

Code Explanation 

No characters available in ring buffer. 

Example: 

Refer to the example following the description of .TTYOUT/.TTOUTR. 
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2.84 .TTYOUT/.TTOUTR 



The requests .TTYOUT and .TTOUTR cause a character to be transmitted to 
the console terminal. The difference between the two requests, as in the 
.TTYIN/.TTINR requests, is that if there is no room for the character in the 
monitor's buffer, the .TTYOUT request waits for room before proceeding, 
while the .TTOUTR does not wait for room and the character is not output. 

If the carry bit is set when execution of the .TTOUTR request is completed, it 
indicates that there is no room in the buffer and that no character was output. 
Under the FB or XM monitor, .TTOUTR normally does not return the carry 
bit set. Instead, the job is blocked until room is available in the output buffer. 
If a job requires execution to continue and the carry bit to be returned, it must 
turn on bit 6 of the Job Status Word before issuing the request. 

The .TTINR and .TTOUTR requests have been supplied to help those users 
who do not need to suspend program execution until a console operation is 
complete. With these modes of I/O, if a no-character or no-room condition 
occurs, the user program can continue processing and try the operation again 
at a later time. 

NOTE 

If a foreground job leaves bit 6 set in the Job Status Word, any 
further foreground .TTYIN or .TTYOUT requests cause the 
system to lock out the background until a character is avail- 
able. Note also that each job in the foreground/background 
environment has its own Job Status Word, and therefore can be 
in different terminal modes independently of the other job. 

Macro Call: .TTYOUT char 
.TTOUTR 



where: 



char is the location containing the character to be loaded in RO and 
printed. If not specified, the character in RO is printed. Upon 
return from the request, RO still contains the character 

Errors: 

Code Explanation 

Output ring buffer full. 
Example: 

.TITLE TTYIN. MAC 



.TTYIN / .TTYOUT - This is an e>:3itiPle in the use of the .TTYIN 
S .TTYOUT recsuests. The example accepts 3 line of input from the 
console Keybosrcfj then echoes it on the terminal. Usin^ .TTYIN % 
.TTYOUT reouests illustrate Synchronous terminal I/Or i.e.i the 
Monitor retains control (the Job is blocked) unti.l the reauests 
are Sc^tlsfiectt 



.MCALL .TTYINj .TTYOUT 
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start: 


MOV 


♦BUFFER, Rl 




CLR 


R2 


INLOOPt 


.TTYIN 


(Rl) + 




INC 


R2 




CMPB 


*12»R0 




BNE 


INLOOP 




MOV 


♦BUFFER. Rl 


OUTLDOP 


: .TTYOUT (Rl>+ 




DEC 


R2 




BEQ 


START 




BR 


OUTLOOP 



BUFFER? .BLKU 



64. 



jRl => Character buffer 

iClesr character count 

fRead char into buffer 

fBump count 

fWas last char a LF ? 

JNo...Set next character 

f Yes . . .F-oint Rl to beainnina of buffer 

JPrint a character 

jDecrease count... 

iDone if count = 

fLoop to print another character 

f Character buffer... 



.END 



START 



.TITLE TTINR.H6C 



.TTINR / .TTOUTR - This is an example in the use of the .TTINR S 
.TTOUTR rectuests. Like TTYIN. MAC, this example accepts lines of 
input from the console ketiboard, then echoes it on the terminal. 
But rather than waitina for the user to type somethina at 'INLOOP' 
or wait for the output buffer to have available space at 'OUTLOOP', 
the routine has been recoded usina .TTINR and .TTOUTR to allow 
other processina to be carried out if a wait condition is reached. 

.MCALL .TTYIN,. TTYOUT 
.MCALL .TTINR, .TTOUTR, .EXIT 



JSU 



44 



start: 


MOV 


♦ BUFFER, Rl 




CLR 


R2 




BIS 


»100,(?^JSU 


inloop: 


.TTINR 






BCS 


NOCHAR 


chrin: 


MOVB 


RO, <R1)+ 




INC 


R2 




CMPB 


R0,^12 




BNE 


INLOOP 




MOV 


♦BUFFER, Rl 


OUTLOOP 


: MOVB 
.TTOUTR 


(R1),R0 




BCS 


NOROOM 


chrout: 


DEC 


R2 




BEQ 


START 




INC 


Rl 




BR 


OUTLOOP 


nochar: 


.TTINR 






BCC 


CHRIN 



BR 



NOCHAR 



noroom: 



MOVB (R1),R0 

.TTOUTR 

BCC CHROUT 



BIC ♦100,e^JSU 

.TTYOUT (Rl) 

BIS ♦lC0,@4JSw 

BR CHROUT 



buffer: .BLKU 
.END 



64. 
START 



Location of Job Status Uord in SYSCOH 

Point Rl to buffer 

Clear character count 

Set bit ♦fi in JSU so . TTINR/. TTOUTR will 

return C bit set if no char/no room... 

Get char from terminal 

None available 

Put char in buffer 

Increase count 

Uas last char = LF? 

No...aet next char 

Yes... point Rl to beainnina of buffer 

Put char in RO 

Try to print it 

Branch if no room in output buffer 

Decrease count 

Done if count=0 

Bump buffer pointer 

then branch to print next char 

Comes here if no char avail 
try to aaain to aet one 
There's one avail this timef 

Do other processina 

Try sSsin 

Comes here if no room in buffer 

Put char in R 

Try to print it aaain 

Successful ! 

Code to be executed while waitina 

Now we must hana to wait... 

Clear bit ^6 in JSU 

Use .TTYOUT to wait for room 

then return to output loop 
Buffer 
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2.85 .TWAIT (FB and XM Only) 

The .TWAIT request suspends the user's job for an indicated length of time. 
.TWAIT requires a queue element and thus should be considered when the 
.QSET request is issued. 

Macro Call: .TWAIT area,time 

where: 

area is the address of a two-word EMT argument block 

time is a pointer to two words of time (high order first, low order 
second), expressed in ticks 

Request Format: 

RO -► area: 



24 



time 



Notes: 

1. Since a .TWAIT is simulated in the monitor using suspend and resume, a 
.RSUM issued from a completion routine without a matching .SPND can 
cause the mainstream to continue past a timed wait before the entire time 
interval has elapsed. In addition, a .TWAIT issued within a completion 
routine is ignored by the monitor, since it would block the job from ever 
running again. 

2. The unit of time for this request is clock ticks, which can be 50 Hz or 60 
Hz, depending on the local power supply. This must be kept in mind when 
the time interval is specified. 

Errors: 

Code Explanation 

No queue element was available. 
Example: 

.TITLE TWAIT. MAC 



.TWAIT - This is sn exemple in the use of the .TWAIT request. 
.TWAIT is useful in applications where a proarsm must be onia 
activated periodically. This eKample will 'wake up' evera five seconds 
to perforni a simulated "task"? and then 'sleep' aSsin. (For example 
Purposes this cycle will be repeated for a maximum of about 35 sec). 



.MCALL 



, TWAIT T .QSET J. EXIT. .PRINT 



STARTS 


CALL 


TASK 


ItJ 


•TWAIT 


•AREAftTIME 




BCS 


NOG 




CALL 


TASK 




DEC 


COUNT 




BNE 


1* 




.PRINT 


♦ BYE 




.EXIT 





rPerform task . . . 

f6o to sleep for 5 seconds 

fBranch if no aueue element 

^Perform task aSain 

fBurop counter - example 3ood for 35 sec 

jBranch if time's not up 

fSay we're thru 

fExit program 



2-138 Programmed Request Description and Examples 



task: 










fPeriodic t3sk simulated here 




INC 


TCNT 






rBump s counter 




bit 


*1,TCNT 






fis it odd? 




BED 


1» 






fBrsnch if not 




.PRINT 


♦ TICK 






(Odd counter prints "tick..." 




RETURN 








jReturn to caller 


1*: 


.PRINT 
RETURN 


♦ TOCK 






JEven counter prints "tock" 
jReturn to caller 


noq: 


.PRINT 
.EXIT 


♦ QERR 






JPrint error messase 
JEnit proarsB 


AREA! 


.WORD 


0,0 






!EMT ArSument block 


time: 


.UORIi 


0»60.*5 


. 




i60 ticks/sec * 5 seconds < = 


count: 


.UORD 


7 






fHaxiniUBi cycles for exsmple 


tcnt: 


.UORD 









j Tick f tock count 


tick: 


.ASCII 


/Tick.. 


./ 


<200> 


jMessaSe text 


tock; 


.ASCIZ 


/Tock/ 








BYE! 


.ASCIZ 


/Ei^ampl 


e 


Concluded/ 


qerr: 


.ASCIZ 


/?No 0- 


El 


ement 


Available?/ 



300 Bites! > 



2.86 .UNLOCK 

(See .LOCK programmed request.) 

2.87 .UNMAP (XM Only) 

The .UNMAP request unmaps a window arxd flags that portion of the pro- 
gram's virtual address space as being inaccessible. When an unmap operation 
is performed for a virtual job, attempts to access the unmapped address space 
cause a memory management fault. For a privileged job, the default (kernel) 
mapping is restored when a window is unmapped. 

Macro Call: .UNMAP area,addr 

where: 

area is the address of a two-word argument block 

addr is the address of the window control block that describes the 
window to be unmapped 

Request Format: 

RO -► area: 



36 



addr 



Errors: 

Code Explanation 

3 An illegal window identifier was specified. 
5 The specified window was not already mapped. 
Example: 

Refer to the example following the description of .CRAW. 
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2.88 .UNPROTECT 

(See .PROTECT programmed request.) 



2.89 .WAIT 



The .WAIT request suspends program execution until all input/output re- 
quests on the specified channel are completed. The .WAIT request, combined 
with the .READ/. WRITE requests, makes double buffering a simple process. 

.WAIT also conveys information through its error returns. An error is returned 
if either the channel is not currently open or the last I/O operation resulted in 
a hardware error. 

In an FB system, executing a .WAIT when I/O is pending causes that job to be 
suspended and another job to run, if possible. 

Macro Call: .WAIT chan 

Request Format: 

RO = 







chan 



Errors: 



Code Explanation 

Channel specified is not open. 

1 Hardware error occurred on the previous I/O operation on this 
channel. 



Example: 



• WAIT 
e:;eiTip 
i n i t i 
msKes 
puts 
resd 
e;-; a flip 
the f 



•TITLE WAIT, MAC 

- This is an eitample in the use of the .WAIT reouest. The 
le denronstrstes ssycnhronous I/O where 3 mainline FToaram 
ates input vis .READ reoueslsr does some other processing 

sure input hss completed via the .UAIT reouestr then out- 
the block Just read. Another .WAIT is issued before the next 
is issued to mske sure the previous write has finished. This 
le is 3 single file copy prosremi utilizing .CSIfiFN to input 
ile specsj load the recsuired handlers and open the files. 



.MCALL 
.MCALL 



.READ. .URITEi .CLOSE, .PRINT 
.CSIGENr .EXIT,. UAIT, , SRE3ET 



start: 



It: 



ERRBYT = 52 

.ENAEL LSB 

.CSIGEN *IiSRACE,*DEFEXT 



MOV 

.READ 

ECS 

r 

BIT 

BNE 



*AREA,R5 

R5,*3 

6* 

♦liIOELK 
2t 



.PRINT *MESSG 

r « 

2t! .WAIT »3 

BCS 5$ 

.WRITE R5,*0 



fError Byte location in SYSCOM 

jEnable local saiiihol block 

iUse CSIGEN to aet handlers, files 

fR5 => EMT Arsument list 

jRead a block . . . 

(Branch an error 

(Then simulate 

jsonre other 

j meaningful (? ). process... 

jDid read finish OK? 

fBranch if not 

iNow write the block Just read 
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BCS 



3$ 



jBrsnch on error 

SCould do some more processing here. 





INC 


lOBLK 




.WAIT 


*0 




BCC 


It 


3*: 


MOV 


♦URERR fRO 


4*: 


.PRINT 

.EXIT 




5$: 


HOV 


♦RDERR tRO 




BR 


4* 


6»; 


TSTB 


@*ERRBYT 




BNE 


5* 




.PRINT 


♦ DONE 




.CLOSE 


♦ 




.SRESET 






.EXIT 




ftREAj; 


.WORD 





lOBLK! 


.UORD 







.UORD 


BUFF 




.WORD 


256. 




.UORD 





buff: 


.BLKU 


256. 


defext; 


.UORD 


0»0i OrO 


done: 


.ASCIZ 


/I-O Transfer C 


hessg; 


.ASCIZ 


<12><15>/< Simu 


urerr: 


.ASCIZ 


/'Urite Error?/ 


rderr: 


.ASCIZ 


/?Re3d Error"?/ 


eof: 


.BYTE 
.EVEN 





DSPACE 


= . 





SBuiiiP block ♦ for next reed 

iUsit for write to finish 

SBrsrich if successful 

;R0 => Write error msS 

rRePort error 

ithen exit program 

tRO => Resd error mss 

(Branch to report error 

iResd error. . .EOF? 

jBrsnch if not 

i Yes ... announce completion 

fMake output file permanent 

jDismiss fetched handlers 

T then exit pros ram 

>EMT Ares block 

jBlock *» 

iBuffer addr S word count 

Jalready fixed in block... 

5 

;i/0 buffer 

!No default extensions for CSIGEN 
omplete/ jMessaSes . . . 
letina Mainline Processing >/ 



;eof flss 



jHsndlers may be loaded starting here 



.END 



START 



2.90 .WDBBK (XM Only) 



The .WDBBK macro defines symbols for the window definition block and 
reserves space for it. Information provided to the arguments of this macro 
permits the creation and mapping of a window through the use of the .CRAW 
request. Note that .WDBBK automatically invokes .WDBDF. 

Macro Call: .WDBBK wnapr,wnsiz[,wnrid,wnoff,wnlen,wnsts] 



where: 



wnapr is the number of the Active Page Register set that includes the 
window's base address. A window must start on a 4K word 
boundary. The valid range of values is from through 7 

wnsiz is the size of this window (expressed in 32-word units) 

wnrid is the identification for the region to which this window maps. 
This argument is optional; supply it if you need to map this 
window. Use the value of R.GID from the region definition 
block for this argument after you create the region to which 
this window must map 

wnoff is the offset into the region at which to start mapping this 
window (expressed in 32-word units). This argument is op- 
tional; supply it if you need to map this window. The default is 
0, which means that the window starts mapping at the region's 
base address 
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wnlen is the amount of this window to map (expressed in 32-word 
units). This argument is optional; supply it if you need to map 
this window. The default value is 0, which maps as much of 
the window as possible 

wnsts is the window status word. This argument is optional; supply 
it if you need to map this window when you issue the .CRAW 
request. Set bit 8, called WS.MAP, to cause .CRAW to per- 
form an implied mapping operation 



Example: 



See Chapter 4 of the RT-11 Software Support Manual for an example 
that uses the .WDBBK macro and a detailed description of the ex- 
tended memory feature. 



2.91 .WDBDF (XM Only) 



The .WDBDF macro defines the symbolic offset names for the window defini- 
tion block and the names for the window status word bit patterns. In addition, 
this macro also defines the length of the window definition block by setting up 
the following symbol: 

W.NLGH = 16 

The .WDBDF macro does not reserve any space for the window definition 
block (see .WDBBK). 

Macro Call: .WDBDF 

The .WDBDF macro expands as follows: 

W.NID = 

W.NAPR = 1 

W.NBAS = 2 

W.NSIZ = 4 

W.NRID = 6 

W.NOFF = 10 

W.NLEN = 12 

W.NSTS = 14 

W.NLGH = 16 

WS.CRW = 100000 

WS.UNM = 40000 

WS.ELW = 20000 

WS.MAP = 400 



2.92 .WRITE/.WRITC/.WRITW 



Write operations for the three modes of RT-11 I/O are done using the 
.WRITE, .WRITC, and .WRITW programmed requests. 
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Note that in the case of .WRITE and .WRITC, additional queue elements 
should be allocated for buffered I/O operations (see .QSET programmed 
request). 

Under an FB monitor with the system job feature, .WRITE/CAV requests may 
be used to send messages to other jobs in the system. 

.WRITE 

The .WRITE request transfers a specified number of words from memory to 

the specified channel. Control returns to your program immediately after the 

Macro Call: .WRITE area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 
chan is a channel number in the range 0-377 (octal) 
buf is the address of the memory buffer to be used for output 
is the number of words to be written 



went 
blk 



is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the start 
of the file. For a non-file-structured .LOOKUP or .ENTER, the 
block number is the absolute block number on the device. The 
user program should normally update blk before it is used 
again. If blk = 0, LP: issues a form feed (This is true for all 
.WRITE requests.) 



Request Format: 
RO -> area: 



11 



chan 



blk 



buf 



went 



NOTE 

When any .WRITE, .WRITC, or .WRITW programmed request 
is returned, RO contains the number of words requested if the 
write is to a sequential-access device (for example, magtape). If 
the write is to a random-access device (disk or DECtape), RO 
contains the number of words that will be written (.W^RITE or 
.WRITC) or have been written (.WRITW). If a request is made 
to write past the end-of-file on a random-access device, the 

woru coiiflL IS siiurbeiicu emu an cirui lo icluxhcu. x hc onun^cuKvi 

word count is returned in RO. Note that the write is done and a 
completion routine, if specified, is entered, unless the request 
cannot be partially filled (shortened word count = 0). 



Programmed Request Description and Examples 2-143 



Errors: 

Code Explanation 

Attempted to write past end-of-file. 

1 Hardware error. 

2 Channel was not opened. 
Example: 

Refer to the example following .READ. 

.WRITC 

The .WRITC request transfers a specified number of words from memory to a 
specified channel. Control returns to the user program immediately after the 
request is queued. Execution of the user program continues until the .WRITC 
is complete, then control passes to the routine specified in the request. When 
an RTS PC is encountered in the completion routine, control returns to the 
user program. 

Macro Call: .WRITC area,chan,buf,wcnt,crtn,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range to 377 (octal) 

buf is the address of the memory buffer to be used for output 

went is the number of words to be written 

crtn is the address of the completion routine to be entered 

blk is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the start 
of the file. For a non-file-structured .LOOKUP or .ENTER, the 
block number is the absolute block number on the device. Your 
program should normally update blk before it is used again. See 
the RT-11 Software Support Manual for the significance of the 
block number for devices such as line printers, and paper tape 
readers 



Request Format: 
RO ->■ area: 



11 



chan 



blk 



buf 



went 



crtn 



NOTE 

When any .WRITE, .WRITC, or .WRITW programmed request 
is returned, RO contains the number of words requested if the 
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write is to a sequential-access device (for example, magtape). If 
the write is to a random-access device (disk or DECtape), RO 
contains the number of words that will be written (.WRITE or 
.WRITC) or have been written (.WTIITW). If a request is made 
to write past the end-of-file on a random-access device, the 
word count is shortened and an error is returned. The shortened 
word count is returned in RO. Note that the write is done and a 
completion routine, if specified, is entered, unless the request 
cannot be partially filled (shortened word count = 0). 

When a .WRITC completion routine is entered, the following conditions are 
true: 

1. RO contains the contents of the channel status word for the opera- 
tion. If bit of RO is set, a hardware error occurred during the 
transfer: Consequently, the data may be unreliable. 

2. Rl contains the octal channel number of the operation. This is 
useful when the same completion routine is to be used for several 
different transfers. 

3. Registers RO and Rl are available for use by the routine, but all 
other registers must be saved and restored. Data cannot be passed 
between the main program and completion routines in any register 
or on the stack. 

Errors: 

Code Explanation 

End-of-file on output. Tried to write outside limits of file. 

1 Hardware error occurred. 

2 Specified channel is not open. 
Example: 

Refer to the example following .RE ADC. 

.WRITW 

The .WRITW request transfers a specified number of words from memory to 

the specified channel. Control returns to your program when the .WRITW is 

complete. 

Macro Call: .WRITW area,chan,buf,wcnt,blk 

where: 

area is the address of a five-word EMT argument block 

chan is a channel number in the range 0-377 (octal) 

buf is the address of the buffer to be used for output 

went is the number of words to be written. The number must be 
positive 
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blk is the block number to be written. For a file-structured 
.LOOKUP or .ENTER, the block number is relative to the start 
of the file. For a non-file-structured .LOOKUP or .ENTER, the 
block number is the absolute block number on the device. Your 
program should normally update blk before it is used again. See 
the RT-11 Software Support Manual for the significance of the 
block number for devices such as line printers and paper tape 
readers. 



Request Format: 
RO ->■ area: 



11 



chan 



blk 



buf 



went 







NOTE 

When any .WRITE, .WRITC, or .WRITW programmed request 
is returned, RO contains the number of words requested if the 
write is to a sequential-access device (for example, magtape). If 
the write is to a random-access device (disk or DECtape), RO 
contains the number of words that will be written (.WRITE or 
.WRITC) or have been written (.WRITW). If a request is made 
to write past the end-of-file on a random-access device, the 
word count is shortened and an error is returned. The shortened 
word count is returned in RO. Note that the write is done and a 
completion routine, if specified, is entered, unless the request 
cannot be partially filled (shortened word' co unt = 0). 

Errors: 

Code Explanation 

Attempted to write past EOF. 

1 Hardware error. 

2 Channel was not opened. 
Example: 

Refer to the example following .READW. 
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Chapter 3 

System Subroutine Description and Examples 



This chapter presents all SYSLIB functions and subroutines in alphabetical 
order and provides a detailed description of each one. An example of each call 
in a FORTRAN program is given. 



3.1 AJFLT 



The AJFLT function converts an INTEGER*4 value to a REAL*4 value and 
returns that result as the function value. 

Form: a = AJFLT (jsrc) 

where: 

jsrc is the INTEGER*4 variable to be converted 
Function Results: 

The function result is a REAL*4 value. 
Errors: 

None. 

Example: 

The following example converts the INTEGER*4 value contained in 
JVAL to single precision (REAL*4), multiplies it by 3.5, and stores the 



REAL#a MALUE »AJFLT 
INTEGER*^ JMAL 



yALUE = AJFLT ( JUAL ) *3 . 5 



3.2 CHAIN 



The CHAIN subroutine allows a background program (or any program in the 
single-job system) to transfer control directly to another background program 
and pass specified information to it. CHAIN cannot be called from a comple- 
tiuii ur interrupt routmt;. iile r v/rt in./\i> impure area is not preserved across 
a chain. Therefore, when chaining from one program to another, the informa- 
tion must be reset in the program being chained to. When chaining to any 
other program, the user should explicitly close the opened logical units with 
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calls to the CLOSE routine. Any routines specified in a FORTRAN USEREX 
library call are not executed if a CHAIN is accomplished (see Appendix B in 
the RT-11/RSTS/E FORTRAN IV User's Guide). 

Form: CALL CHAIN (dblk,var,wcnt) 
where: 

dblk is the address of a four-word Radix-50 descriptor of the file 
specification for the program to be run (see the PDP-11 FOR- 
TRAN Language Reference Manual for the format of the file 
specification). 

var is the first variable (which must start on a word boundary) in a 
sequence of variables with increasing memory addresses to be 
passed between programs in the chain parameter area (absolute 
locations 510 to 777). A single array or a COMMON block (or 
portion of a COMMON block) is a suitable sequence of variables 

went is a word count specifying the number of words (beginning at 
uar) to be passed to the called program. The argument went 
may not exceed 60. If no words are passed, then a word count of 
must be supplied 

If the size of the chain parameter area is insufficient, it can be increased by 
specifying the /B (or /BOTTOM) option to LINK for both the program exe- 
cuting the CHAIN call and the program receiving control. 

The data passed can be accessed through a call to the RCHAIN routine. For 
more information on chaining to other programs, see the .CHAIN pro- 
grammed request (Section 2.2). 

Errors: 

None. 
Example: 

The following example transfers control from the main program to 
PROG.SAV on DTO, and passes it variables. 



INTEGER#2 DATA(IO) 

DATA SPEC/GRDTOPRO, ERG SAU/ 



CALL CHAIN ( SPEC »DATA , 1 ) 



3.3 CLOSEC/ICLOSE 



The CLOSEC subroutine terminates activity on the specified channel and 
frees it for use in another operation. The handler for the associated device 
must be in memory. CLOSEC cannot be called from a completion or interrupt 
routine. 
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Form: CALL CLOSEC (chan[,i]) 
i = CLOSEC(chan) 
CALL ICLOSE (chan[,i]) 
i = ICLOSE(chan) 

where: 

chan is the channel number to be closed. This argument must be 
located so that the USR cannot swap over it 

i is the error return if a protection violation occurs 

A CLOSEC or PURGE must eventually be issued for any channel opened for 
input or output. A CLOSEC call specifying a channel that is not open is 
ignored. 

A CLOSEC performed on a file that was opened via an TENTER causes the 
device directory to be updated to make that file permanent. If the device 
associated with the specified channel already contains a file with the same 
name and type, the old copy is deleted when the new file is made permanent. 
If the file already open is protected, then a protection error is generated. 
A CLOSEC on a file opened via LOOKUP does not require any directory 
operations. 

When an entered file is closed, its permanent length reflects the highest block 
of the file written since the file was entered; for example, if the highest block 
written is block number 0, the file is given a length of 1; if the file was never 
written, it is given a length of 0. If this length is less than the size of the area 
allocated at lENTER time, the unused blocks are reclaimed as an empty area 
on the device. 

Errors: 

i = Normal return. 
= -4 A protected file with the same name already exists on a device. 
The CLOSEC is performed, resulting in two files on the device 
with the same name. 

Example: 

The following example creates and processes a 56-block file. 

REAL*a DBLK(2) 

DATA DBLK/BRSYONEW ,GRFILDAT/ 

DATA ISIZE/5G/ 



ICHAN=IGETC( ) 

IF( ICHAN.LT.O) GOTO 100 

I ERR = I ENTER! I CHAN »DBLK »ISIZE) 

IF(IERR.LT.O)GOTO 20 

GOTO ( 1 10 . IZO f 130 ) flBS( lER ) 

CALL ICLOSE (ICHANtI) 

IF(I.EO.-il) GOTO 200 

CALL IFREEC( ICHAN) 

CALL EXIT 
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100 STOP 'NO AVAILABLE CHANNELS' 

110 STOP 'CHANNEL ALREADY IN USE' 

120 STOP 'NOT ENOUGH ROOM ON DEUICE' 

130 STOP 'DEVICE IN USE' 

200 STOP 'PROTECTION ERROR' 
END 



3.4 CONCAT 

The CONCAT subroutine concatenates two character strings. 

Form: CALL CONCAT (a,b,out[,len[,err]]) 

where: 

a is the array containing the left string. The string must be termi- 
nated with a null byte 

b is the array containing the right string. The string must be termi- 
nated with a null byte 

out is the array into which the concatenated result is placed. This 
array must be at least one element longer than the maximum 
length of the resultant string (that is, one greater than the value of 
len, if specified) 

len is the integer number of characters representing the maximum 
length of the output string. The effect of len is to truncate the 
output string to a given length, if necessary 

err is the logical error flag set if the output string is truncated to the 
length specified by len 

CONCAT sets the string in the array out to be the string in array a immedi- 
ately followed on the right by the string in array b and a terminating null 
character. 

NOTE 

Any combination of string arguments is allowed, so long as b 
and out do not specify the same array. 

Concatenation stops when a null character is detected in b, or when the 
number of characters specified by len has been moved. 

If either the left or right string is a null string, the other string is copied to out. 
If both are null strings, then out is set to a null string. The old contents of out 
are lost when this routine is called. 



Errors: 



Error conditions are indicated by err^ if specified. If err is given and the 
output string would have been longer than len characters, then err is set 
to .TRUE.; otherwise, err is unchanged. 
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Example: 

The following example concatenates the string in array STR and the 
string in array IN and stores the resultant string in array OUT. OUT 
cannot be larger than 29 characters. 



LOGICAL*! IN (22) .OUT (30) .STR(7) 



CALL CONCATOTR ,IN »0UT.29) 



3.5 CVTTIM 



The CVTTIM subroutine converts a two-word internal format time to hours, 
minutes, seconds, and ticks. 

Form: CALL CVTTIM (time,hrs,min,sec,tick) 

where: 

time is the two-word internal format time to be converted. If time is 
considered as a two-element INTEGER*2 array, then: 

time (1) is the high-order time 
time (2) is the low-order time 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second for 60-cycle 
clocks; 1/50 of a second for 50-cycle clocks) 

Errors: 

None. 

Example: 

INTEGER#4 ITIME 



CALL GTIH(ITIME) ! GET CURRENT TIME-OF-DAY 

CALL CVTTIM ( I T IME 1 1 HRS , I M I N , I SEC » I TCK ) 

IF( IHRS.GE. 12.AND. IHRS.LT.13) GOTO 100 !TIME FOR LUNCH 



3.6 DtViCt (FB and XM Oniy) 

The DEVICE subroutine allows you to set up a list of addresses to be loaded 
with specified values when the program is terminated. If a job terminates or is 
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aborted with a CTRL/C from the terminal, this list is picked up by the system 
and the appropriate addresses are set up with the corresponding values. 

This function is primarily designed to allow user programs to load device 
registers with necessary values. In particular, it is used to turn off a device's 
interrupt enable bit when the program servicing the device terminates. 

Only one address list can be active at any given time; hence, if multiple 
DEVICE calls are issued, only the last one has any effect. The list must not be 
modified by the program after the DEVICE call has been issued, and the list 
must not be located in an overlay or an area over which the USR swaps. 

The second argument of the call (link) provides support for a linked list of 
tables. The link argument is optional and causes the first word of the list to be 
processed as the link word. 

Form: CALL DEVICE (ilistl,link]) 
where: 

ilist is an integer array that contains two-word elements, each com- 
posed of a one-word address and a one-word value to be put at 
that address, terminated by a zero word. On program termina- 
tion, each value is moved to the corresponding address 

link is an optional argument that can be any value. This indicates 
that a linked list table is to be used 

If the linked list form is used the first word of the array is the link 
list pointer 

For more information on loading values into device registers, see the .DEVICE 
programmed request (Section 2.15). 

Errors: 

None. 

Example: 



INTEGER*2 IDRllO) 
DATA IDRll ( 1 )/"167770/ 
DATA IDRll (2) /O/ 
DATA IDRll(3)/0/ 
CALL DEMICE( IDRll ) 



IDEUICE ARRAY SPEC 

IDRll CSR ADDRESS (OCTAL) 

IMALUE TO CLEAR INTERRUPT ENABLE 

!AND END-OF-LIST FLAG 

!SET UP FOR ABORT 



3.7 DJFLT 



The DJFLT function converts an INTEGERS value into a REAL*8 
(DOUBLE PRECISION) value and returns that result as the function value. 

Form: d = DJFLT (jsrc) 

where: 

jsrc specifies the INTEGER*4 variable to be converted 



3-6 System Subroutine Description and Examples 



Notes: 

If DJFLT is used, it must be defined in the FORTRAN program, either 
explicitly (REAL*8 DJFLT) or implicitly (IMPLICIT REAL*8 (D)). Without 
a definition, DJFLT is assumed to be REAL*4 (single precision). 

Function Results: 

The function result is the REAL*8 value that is the result of the operation. 

Errors: 

None. 
Example: 

INTEGER*a JVAL 
REAL*8 DJFLT tD 

D=DJFLT( JMAL) 



3.8 GETSTR 



The GETSTR subroutine reads a formatted ASCII record from a specified 
FORTRAN logical unit into a specified array. The data is truncated (trailing 
blanks removed) and a null byte is inserted at the end to form a character 

string. 

GETSTR can be used in main program routines or in completion routines, but 
it cannot be used in both at the same time. If GETSTR is used in a comple- 
tion routine, it cannot be the first I/O operation on the specified logical unit. 

Form: CALL GETSTR (lun,out,len,err) 

where: 

lun is the integer FORTRAN logical unit number of a formatted se- 
quential file from which the string is to be read 

out is the array to receive the string; this array must be at least one 
element longer than len 

len is the integer number representing the maximum length of the 
string that is allowed to be input 

err is the LOGICAL*! error flag that is set to .TRUE, if an error 
occurred. If an error did not occur, it is .FALSE. 

Errors: 

Error conditions are indicated by err. If err is .TRUE., the values re- 
turned are as follows: 

err = -1 End-of-file for a read operation, 
err = -2 Hard error for a read operation, 
err = -3 More than len bytes were contained in a record. 
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Example: 



The following example reads a string of up to 80 characters from logical 
unit 5 into the array STRING. 



LOGICAL*! STRING(S1 ) >ERR 



CALL GETSTR(5 .STRINGjBO »ERRi 



3.9 GTIM 



The GTIM subroutine returns the current time of day. The time is returned in 
two words and is given in terms of clock ticks past midnight. If the system 
does not have a line clock, a value of is returned. If an RT-11 monitor TIME 
command has not been entered, the value returned is the time elapsed since 
the system was bootstrapped, rather than the time of day. 

Form: CALL GTIM (itime) 

where: 

itime is the two-word area to receive the time of day 

The high-order time is returned in the first word, the low-order time in the 
second word. The CVTTIM routine (see Section 3.5) can be used to convert 
the time into hours, minutes, seconds and ticks. CVTTIM performs the con- 
version based on the monitor configuration word for 50- or 60-cycle clocks. 
Under an FB or XM monitor, the time-of-day is automatically reset after 
24:00 when a GTIM is executed; under the single-job monitor, it is not. 

Errors 

None. 

Example: 

INTEGER#4 JTIME 



CALL GTIM(JTIME) 

3.10 GTJB/IGTJB 

The GTJB subroutine returns information about a job in the system. 

Form: CALL GTJB (addr,|jobblk [,i]]) 
i = GTJB (addrjjobblk]) 
CALL IGTJB (addr,[jobblk [,i]]) 
i = IGTJB (addr,tJobblk]) 
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where: 

addr is the address of an eight- or twelve-word block into which the 
parameters are passed 

The parameters returned are as follows: 

Word 1 Job Number = priority level*2 (background job is 
0, system jobs are 2, 4, 6, 10, 12, 14, foreground 
job is 16 in system job monitors; background job 
is forefround iob is 2 in FB and XM monitors" 
job number is in SJ monitor) 

2 High-memory limit of job partition (last location 
plus 2) 

3 Low-memory limit of job partition (first location) 

4 Pointer to I/O channel space 

5 Address of job's impure area in FB and XM moni- 
tors (0 in SJ) 

6 Low byte: unit number of job's console terminal 
(only if the multi-terminal option is present; in 
SJ and when the multi-terminal feature is not 
used) 

7 Virtual high limit for a job created with the linker 
A'^ option (XM only; in SJ and FB and where 
the Linker /N option is not used) 

8-9 Reserved for future use 
10-12 ASCII logical job name ^(system job monitors 
only) 

jobblk is a pointer to a three-word ASCII job name for which data is 
being requested. Do not specify this argument when requesting 
the eight-word block 

i is an error return if the job is not running 

If one argument is used with the call, only the first eight parameters will be 
passed. For example, 

INTEGER IJPARM(8) 
CALL GTJB (IJPARM) 
I = GTJB (IJPARM) 

At least a comma must follow the argument to pass the information into a 
12-word block. For example, 

INTEGER IJPARM(12) 
CALL GTJB (IJPARM,) 
I = GTJB (IJPARM,) 



Hirrors: 



i = Normal return. 
= -1 No such job currently running. 
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Example: 



C THIS IS AN EXAMPLE UNDER A SYSTEM 
C JOB MONITOR TO SEE IF THE FOREGROUND 
C JOB IS RUNNING 
DIMENSION JDATA( 12) 



10 
20 



I = GTJB (JOATA, IG) 

IF < I ,EQ,0) GOTO 20 

TYPE 10 

FORMATf 'NO FG JOB! ' ) 

STOP 



3.11 GTLIN 



The GTLIN subroutine transfers a line of input from the console terminal or 
an active indirect command file to the user program. This request allows you 
to input information at the console terminal, and it allows the program to 
operate through indirect files. This subroutine requires the USR. The maxi- 
mum size of the input line is 80 characters. See the .GTLIN programmed 
request for setting bits in the Job Status Word to pass lower-case letters and 
to establish a non terminating condition. 

Form: CALL GTLIN (result[,prompt]) 

where: 



result 



prompt 



is the array receiving the string. This LOGICAL*! array con- 
tains a maximum of 80 characters plus as the end indicator, 
and therefore must be dimensioned to at least 81 elements 

is a LOGICAL*! array containing an optional prompt string 
to be printed before the input line is received. The string 
format is the same as that used by the PRINT subroutine. If 
this argument is not present, no prompt is printed 



Errors: 

None. 
Example: 



LOGICAL* I1\IP(B0) ,PROMT(E) 

DATA PROMT /' N '» 'A '. 'M ',' E ','?',' 200/ 



CALL GTLIN( INP .PROMT) 
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3.12 lADDR 

The lADDR function returns the 16-bit absolute memory address of its argu- 
ment as the integer function value. 

Form: i = lADDR (arg) 

where: 

arg is the variable or constant whose memory address is to be ob- 
tained. The value obtained by passing an expression as arg is 
unpredictable 

Errors: 

None. 

Example: 

lADDR can be used to find the address of an assembly language global 
area. For example: 

EXTERNAL CAREA 
J=IADDR(CAREA) 



3.13 lAJFLT 

The lAJFLT function converts an INTEGER*4 value to a REAL*4 value and 
stores the result. 

Form.: i = lAJFLT (jsrc,ares) 

where: 

jsrc is the INTEGER*4 variable to be converted 

ares is the REAL*4 variable or array element to receive the converted 
value 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 Significant digits were lost during the conversion. 

Example: 

INTEGER*a JMAL 
REAL*a RESULT 



IF(IAJFLT( JMAL -RESULT) .EO, -2) TYPE 93 
93 FORMAT (' OUERFLOW IN INTEGER*4 TO REAL CONVERSION') 
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3.14 lASIGN 



The lASIGN function sets information in the FORTRAN logical unit table 
(overriding the defaults) for use when the FORTRAN Object Time System 
(OTS) opens the logical unit. This function can be used with ICSI (see 
Section 3.19) to allow a FORTRAN program to accept a standard CSI input 
specification. lASIGN must be called before the unit is opened; that is, before 
any READ, WRITE, PRINT, TYPE, ACCEPT, or OPEN statements are 
executed that reference the logical unit. 

Form: i = lASIGN (lun,idev[,ifiltyp[,isize[,itype]]]) 

where: 



lun 



idev 



ifiltyp 



isize 



itype 



is an INTEGER*2 variable, constant, or expression specifying 
the FORTRAN logical unit for which information is being 
specified 

is a one-word Radix-50 device name; this can be the first word 
of an ICSI input or output file specification 

is a three-word Radix-50 file name and file type; this can be 
words 2 through 4 of an ICSI input or output file specification 

is the length (in blocks) to allocate for an output file; this can 
be the fifth word of an ICSI output specification. If 0, the 
larger of either one-half the largest empty segment or the en- 
tire second largest empty segment is allocated. If the value 
specified for length is -1, the entire largest empty segment is 
allocated 

is an integer value determining the optional attributes to be 
assigned to the file. This value is obtained by adding the val- 
ues that correspond to the desired operations: 

1 Use double buffering for output. 

2 Open the file as a temporary file. 

4 Force a LOOKUP on an existing file during the first I/O 
operation. (Otherwise, the first FORTRAN I/O operation 
clei/8rmmes nOw liic lue is opened. iNormaily if the first I/O 
operation is a write, an lENTER would be performed on 
the specified logical unit. A read always causes a 
LOOKUP.) 
8 Expand carriage control information (see Notes below). 
16 Do not expand carriage control information. 
32 File is read only. 



Notes: 



Expanded carriage control information applies only to formatted output files 
and means that the first character of each record is used as a carriage control 
character when processing a write operation to the given logical unit. The first 
character is removed from the record and converted to the appropriate ASCII 
characters to simulate the requested carriage control. 
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If carriage control information is not expanded, the first character of each 
record is unmodified and the FORTRAN OTS outputs a line feed, followed by 
the record, followed by a carriage return. 

If carriage control is unspecified, the FORTRAN OTS sends expanded car- 
riage control information to the terminal and line printer and sends unex- 
panded carriage control information to all other devices and files. See the 
PDP-11 FORTRAN Language Reference Manual for further carriage control 
information. 



Errors: 



i = Normal return. 

<> The specified logical unit is already in use, or there is no 
space for another logical unit association. 



Example: 



The following example (1) creates an output file on logical unit 3, using 
the first output file given to the RT-11 Command String Interpreter 
(CSI), (2) sets up the output file for double buffering, (3) creates an 
input file on logical unit 4, based on the first input file specification 
given to the RT-11 CSI, and (4) makes the input file available for read- 
only access. 



INTEGER#2 SPEC(39) 

REAL#a EKT(2) 

DATA EXT/GRDATDAT ,BRDATDAT/ 



IDEFAULT FILE TYPE IS DAT 



3.15 ICDFN 



10 IF( ICSI (SPEC »TYP t . >0:) ,NE.O) GOTO 10 

C 

C DO NOT ACCEPT ANY SWITCHES 

C 

CALL lASIGNO ,SPEC( 1 ) .SPEC (2) .SPEC(5) ,1 ) 
CALL !ASIGN(4fSPEC(16) .SPEC<17) .0.32) 



The ICDFN function increases the number of input/output channels. Note 
that ICDFN defines new channels; any channels defined with an earlier 
ICDFN function are not used. Thus, an ICDFN for 20 (decimal) channels 
(while the 16 [decimal] original channels are defined) causes only 20 I/O chan- 
nels to exist; the space for the original 16 is unused. The space for the new 
channel area is allocated out of the free space managed by the FORTRAN 
system. 

Form: i = ICDFN (num[,area]) 



wnere: 



num 



is the integer number of channels to be allocated. The number of 
channels must be greater than 16 and can be a maximum of 256. 
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The program can use all new channels greater than 16 without a 
call to IGETC; the FORTRAN system input/output uses only 
the first 16 channels. This argument must be positioned so that 
the USR cannot swap over it 

area is the space allocated from within the calling program. Under FB 
and SJ monitors; be sure that the space is outside the USR 
swapping area. If this argument is not specified, the space for 
the channels is allocated in the FORTRAN OTS work area 

Notes: 

1. ICDFN cannot be issued from a completion or interrupt routine. 

2. It is recommended that the ICDFN function be used at the beginning of 
the main program before any I/O operations are initiated. 

3. If ICDFN is executed more than once, a completely new set of channels is 
created each time ICDFN is called. 

4. ICDFN requires that extra memory space be allocated to foreground pro- 
grams (see Section 1.2.4.1). 

5. Any channels that were open prior to the ICDFN are copied over to the 
new set of channel status tables. 

Function Results: 

i = Normal return. 
= 1 An attempt was made to allocate fewer channels than already 

exist. 
= 2 Not enough free space is available for the channel area. 

Example: 

IFC ICDFl\l(2a) ,E0.2) STOP 'NOT ENOUGH MEMORY' 



3.16 ICHCPY (FB and XM Only) 

file that is currently open by another job for either input or output. This 
function can be used by either the foreground or the background job. An 
ICHCPY must be done before the first read or write for the given channel. 

Form: i = ICHCPY (chan,ochan[,jobblk]) 
where: 

chan is the channel the job will use to read the data. You must 
obtain this channel through an IGETC call, or you can use 
channel 16 or higher if you have done an ICDFN call 

ochan Is the channel number of the other job that is to be copied 

jobblk is a pointer to a three-word ASCII job name 
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Notes: 

1. If the other job's channel was opened with an lENTER function or a 
.ENTER programmed request to create a file, your channel indicates a file 
that extends to the highest block that the creator of the file had written at 
the time the ICHCPY was executed. 

2. A channel that is open on a sequential-access device should not be copied, 
because buffer requests can become intermixed. 

3. Your program can write to a file (that is being created by the other job) on 
a copied channel, just as it could if it were the creator. When your channel 
is closed, however, no directory update takes place. 

Errors: 

i = Normal return. 
= 1 Specified job does not exist or does not have the specified 

channel (ochan) open. 
= 2 Channel {chan) is already open. 



3.17 ICLOSE 

See the SYSLIB subroutine CLOSEC. 



3.18 ICMKT 



The ICMKT function cancels one or more scheduling requests (made by an 
ISCHED, ITIMER, or MRKT routine). Support for ICMKT in SJ requires 
that timer support be created through SYSGEN. 

Form: i = ICMKT (id,time) 

where: 

id is the identification integer of the request to be canceled. If id is 

equal to 0, all scheduling requests are canceled 

time is the name of a two- word area in which the monitor returns the 
amount of time remaining in the canceled request 

For further information on canceling scheduling requests, see the .CMKT 
programmed request (Section 2.5). 



Errors: 



i = Normal return. 
= 1 id was not equal to and no scheduling request with that 
identification could be found. 
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Example: 

INTEGER#a J 

* 

CALL ICMKT(OfJ) ! ABORT ALL TIMER REQUESTS NOW 
END 



3.19 ICSI 



The ICSI function calls the RT-11 Command String Interpreter in special 
mode to parse a command string and return file descriptors and options to the 
program. In this mode, the CSI does not perform any handler IFETCHes, 
CLOSECs, lENTERs, or LOOKUPs. This argument is allowed only when the 
input is from the console terminal. ICSI cannot be called from a completion or 
interrupt routine. This subroutine requires the USR. 

Form: i = ICSI (filspc,deftyp,[cstring],[option],n) 
where: 

filspc is the 39- word area to receive the file specifications. The for- 
mat of this area (considered as a 39-element INTEGER*2 
array) is: 

Word 1 output file number 1 

4 specification 

5 output file number 1 length 

6 output file number 2 
9 specification 

10 output file number 2 length 

11 output file number 3 

14 specification 

15 output file number 3 length 

16 input file number 1 

19 specification 

20 input file number 2 

23 specification 

24 input file number 3 

27 specification 

28 input file number 4 

31 specification 

32 input file number 5 

35 specification 

36 input file number 6 
39 specification 
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deftyp 



cstring 



option 



Notes: 



is the table of Radix-50 default file types to be assumed when 
a file is specified without a file type: 

deftyp(l) is the default for all input file types 

deftyp(2) is the default file type for output file number 1 

deftyp(3) is the default file type for output file number 2 

deftyp(4) is the default file type for output file number 3 

is the area that contains the ASCIZ command string to be 
interpreted; the string must end in a zero byte. If the argu- 
ment is omitted, the system prints the prompt character (*) 
at the terminal and accepts a command string. If input is 
from an indirect command file, the next line of that file is 
used 

is the name of an INTEGER*2 array dimensioned (4,n) where 
n represents the number of options defined to the program. 
This argument must be present if the value specified for n is 
non-zero. This array has the following format for the jth op- 
tion described by the array: 

option(l,j) is the one-character ASCII name of the option 
option(2,j) is set by the routine to 0, if the option did not 

occur; to 1, if the option occurred without a 

value; to 2, if the option occurred with a value 
option(3,j) is set to the file number on which the option is 

specified 
option(4,j) is set to the specified value if option(2,n) is equal 

to 2 

is the number of options defined in the array option 



1. The array option must be set up to contain the names of the valid options. 
For exami^le use the foUowin*'' to set mj^ names for five options: 

INTEGER*2 SWCa»5) 

DATA SW ( 1 . 1 ) /' S ' / . SW ( 1 f 2 ) / ' M ' / » SW ( 1 * 3 ) / ' I '■ / 

DATA SW( 1 .a)/'L'/ »SW(1 .5)/ 'E'/ 

2. Multiple occurrences of the same option are supported by allocating an 
entry in the option array for each occurrence of the option. Each time the 
option occurs in the option array, the next unused entry for the named 
option is used. 

3. The arguments of ICSI must be positioned so that the USR cannot swap 
over them. For more information on calling the Command String Inter- 
preter, see the .CSISPC programmed request (Section 2.10). 

Errors: 



Normal return. 

i Illegal command line; no data was returned. 

2 

3 



An illegal device specification occurred in the string. 

An illegal option was specified, or a given option was specified 

more times than were allowed for in the option array. 
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Example: 



The following example causes the program to loop until a valid com- 
mand is typed at the console terminal. 



INTEGER*2 SPEC(33) 

REAL*4 EKT(2) 

DATA EXT/GRDATDAT ,GRDATDAT/ 



10 TYPE 99 

99 FORHAT (' ENTER UALID CBI STRING WITH NO OPTIONS') 
IF( ICSKSPEC tEKT » » fO) .NE.O) GOTO 10 



3.20 ICSTAT (FB and XM Only) 

The ICSTAT function obtains information about a channel. It is supported 
only in the FB or XM environment; no information is returned under the 
single-job monitor. 

Form: i = ICSTAT (chan,addr) 

where: 

chan is the channel whose status is desired 

addr is a six-word area to receive the status information. The area, as 
a six-element INTEGER*2 array, has the following format: 

Word 1 channel status word 

2 starting absolute block number of file on this channel 

3 length of file 

4 highest block number written since file was opened 

5 unit number of device with which this channel is asso- 
ciated 

6 Radix-50 of device name with which the channel is 
associated 



Errors: 



i = Normal return. 



Channel specified is not open. 



Example: 



The following example obtains channel status information about 
channel I. 



99 



INTEGER#2 AREA(G) 

1=7 

IF(ICSTAT{ I (AREA) ,NE,0) TYPE 33 > I 

FORHAT( IK , 'CHANNEL' ,Iil , 'IB NOT OPEN') 
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3.21 IDELET 



The IDELET function deletes a named file from an indicated device. 
IDELET requires the USR and cannot be issued from a completion or inter- 
rupt routine. 

Form: i = IDELET (chan,dblk[,seqnum]) 

where: 

chan is the channel to be used for the delete operation. You must 

obtain this channel through an IGETC call, or you can use 
channel 16 (decimal) or higher if you have done an ICDFN 
call 

dblk is the four-word Radix-50 specification (dev:filnam.typ) for 

the file to be deleted 

seqnum is the file number for cassette operations: if this argument is 
blank, a value of is assumed 

For magtape operation, it describes a file sequence number 
that can have the following values: 

Value Meaning 

-1 This value suppresses rewinding and searching for a 
file name from the current tape position. Note that if 
the position is unknown, the handler executes a posi- 
tioning algorithm that involves backspacing until an 
end-of-file label is found. The user should not use any 
other value since all other negative values are re- 
served for future use. 

This value rewinds the magtape and spaces forward 
until the file name is found. 

n Where n is any positive number. This value positions 
the magtape at file sequence number n. If the file 
represented by the file sequence number is greater 
than two files away from the beginning of the tape, a 
rewind is performed. If not, the tape is backspaced to 
the file. 



NOTE 

The arguments of IDELET must be located so that the USR 
cannot swap over them. 



T^l — r. Ac: — ] „u„ 1 



^^c^. ;, 



;,,„ ,,.1,^ <-U„ Tr»T7T T7"T' ; ™„l„4-„ TTltriT T^'T 

1 lie opcv-iiicu uiiaiiiici lo iciL iiiatuvc wncii liic ii^ihi^ilh x lo uuiiipictc. i.i-/izii^iii i. 

requires that the handler to be used be resident (via an IFETCH call or a 
LOAD command from KMON) at the time the IDELET is issued. If the 
handler is not resident, a monitor error occurs. 
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For further information on deleting files, see the .DELETE programmed 
request (Section 2.14). 

Errors: 

i = Normal return. 

= 1 Channel specified is already open. 

= 2 File specified was not found. 

= 3 Device in use. 

= 4 The file is protected and cannot be deleted. 

Example: 

The following example deletes a file named FTN5.DAT from SYO. 

REAL#4 FILNAM(2) 

DATA FILNAH/6RSY0FTN .BR5 DAT/ 



I=IGETC( ) 

IFCLT.O) STOP 'NO CHANNEL' 

CALL IDELET( I ,FILNAM) 

CALL IFREECd) 



3.22 IDJFLT 

The IDJFLT function converts an INTEGER*4 value into a REAL*8 
(DOUBLE PRECISION) value and stores the result. 

Form: i = IDJFLT (jsrc,dres) 

where: 

jsrc specifies the INTEGER*4 variable that is to be converted 

dres specifies the REAL*8 (or DOUBLE PRECISION) variable to 
receive the converted value 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

INTEGER*4 JJ 
REAL#B DJ 



IF(IDJFLT( JJ ,DJ) .LE.O) TYPE 39 
99 FORHAT (' MALUE IS NOT POSITIME') 
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3.23 IDSTAT 



The IDSTAT function obtains information about a particular device. It 
requires the USR and cannot be issued from a completion or interrupt routine. 

Form: i = IDSTAT (devnam,cblk) 

where: 

devnam is the Radix-50 device name 

cblk is the four-word area used to store the status information. 

The area, as a four-element INTEGER*2 array, has the fol- 
lowing format: 

Word 1 device status word (see Section 2.24) 

2 size of handler in bytes 

3 entry point of handler (non-zero implies that the 
handler is in memory) 

4 size of the device (in 256-word blocks) for block- 
replaceable devices; zero for sequential-access 
devices 

NOTE 

The arguments of IDSTAT must be positioned so that the USR 
cannot swap over them. 

IDSTAT looks for the device specified by devnam and, if found, returns four 
words of status in cblk. 

Errors: 

i = Normal return. 
= 1 Device not found in monitor tables. 

Example: 

The following example determines whether the line printer handler is in 
memory. If it is not, the program stops and prints a message to indicate 
that the handler must be loaded. 

INTEGER IDNAM 

INTEGEry*2 CBLK(a) 

DATA IDNAM/3RLP / 

DATA CBLK/4#0/ 

CALL IDSTAT( IDNAM .CBLK) 

IF(CBLK!3) .EO.O) STOP 'LOAD THE LP HANDLER AND RERUN' 



3.24 lENTER 



The lENTER function allocates space on the specified device and creates a 
tentative directory entry for the named file. If a file of the same name already 
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exists on the specified device, it is not deleted until the tentative entry is 
made permanent by CLOSEC or ICLOSE. The file is attached to the channel 
number specified. This routine requires the USR. 

Form: i = lENTER (chan,dblk,length[,seqnum]) 

where: 



chan 



dblk 



length 



seqnum 



is the integer specification for the RT-11 channel to be asso- 
ciated with the file. You must obtain this channel through an 
IGETC call, or you can use channel 16 or higher if you have 
done an ICDFN call 

is the four-word Radix-50 descriptor of the file to be operated 
upon 

is the integer number of blocks to be allocated for the file. If 
0, the larger of either one-half the largest empty segment or 
the entire second largest empty segment is allocated. If the 
value specified for length is -1, the entire largest empty seg- 
ment is allocated (see the .ENTER programmed request, 
Section 2.27). 

is a file number for cassette. If this argument is blank, a 
value of is assumed. 

For magtape, it describes a file sequence number that can 
have the following values: 

-2 Rewind the magtape and space forward until the file 
name is found, or until logical end-of-tape is detected. 
The magtape is now positioned correctly. A new logical 
end-of-tape is implied. 

-1 Space to the logical-end-of-tape and enter file. 

Rewind the magtape and space forward until the file 
name is found or the logical-end-of-tape is detected. If 
the file name is found, an error is generated. If the file 
name is not found, then enter file. 

n Position magtape at file sequence number n if n is 
greater than zero and the file name is not null. 



Notes: 

1. lENTER cannot be issued from a completion or interrupt routine. 

2. lENTER requires that the appropriate device handler be in memory. 

3. The arguments of lENTER must be positioned so that the USR does not 
swap over them. 
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For further information on creating tentative directory entries, see the 
.ENTER programmed request (Section 2.27). 



Errors: 



= n 

= -1 
= -2 

= -3 

= -4 
= -5 



Example: 



Normal return; number of blocks actually allocated (n = 

for non-file-structured lENTER). 

Channel {chan) is already in use. 

In a fixed-length request, no space greater than or equal to 

length was found. 

Device in use. 

A file by that name already exists and is protected. 

File sequence number not found. 



The following example allocates a channel for file TEMP.TMP on SYO. 
If no channel is available, the program prints a message and halts. 



REAL*fl DBLK(2) 

DATA DBLK/6RSY0TEM .BRP TMP/ 

ICHAN=IGETC( ) 

IF(ICHAN.LT.O) STOP 'NO AUAILABLE CHANNEL' 

CREATE TEMPORARY WORK FILE 

IF( IENTER{ ICHAN »DBLK f20 ) .LT.O J STOP 'ENTER FAILURE' 



CALL PURGE( ICHAN) 
CALL IFREEC(ICHAN) 



3.25 IFETCH 



The IFETCH function loads a device handler into memory from the system 
device, making the device available for input/output operations. The handler 
is loaded into the free area managed by the FORTRAN system. Once the 
handler is loaded, it cannot be released and the memory in which it resides 
cannot be reclaimed. IFETCH requires the USR and cannot be issued from a 
completion or interrupt routine. 

Form: i = IFETCH (devnam) 

where: 

devnam is the one-word Radix-50 name of the device for which the 
handler is desired. This argument can be the first word of an 
ICSI input or output file specification. This argument must 
Kg T^ositioned so that the USR cannot swap over it 
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For further information on loading device handlers into memory, see the 
.FETCH programmed request (Section 2.29). 



Errors: 



i = Normal return. 
= 1 Device name specified does not exist. 
== 2 Not enough room exists to load the handler. 
= 3 No handler for the specified device exists on the system 
device. 



Example: 



The following example requests that the DX handler be loaded into 
memory; execution stops if the handler cannot be loaded. 



REAL#a IDNAM 
DATA IDNAM/3RDX/ 



IF ( IFETCH(IDNAM) .NE.O) STOP 'FATAL ERROR FETCHING HANDLER 



3.26 IFREEC 



The IFREEC function returns a specified RT-11 channel to the available pool 
of channels. Before IFREEC is called, the specified channel must be closed or 
deactivated with a CLOSEC or ICLOSE (see Section 3.3) or a PURGE (see 
Section 3.87) call. IFREEC cannot be called from a completion or interrupt 
routine. IFREEC calls must be issued only for channels that have been suc- 
cessfully allocated by IGETC calls; otherwise, the results are unpredictable. 

Form: i = IFREEC (chan) 

where: 

chan is the integer number of the channel to be freed 
Errors: 

i = Normal return. 
= 1 Specified channel is not currently allocated. 

Example: 

See the example under IGETC. 



3.27 IGETC 



The IGETC function allocates an RT-11 channel, in the range 0-17 (octal), to 
be used by other SYSLIB routines and marks it in use so that the FORTRAN 
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I/O system will not access it. IGETC cannot be issued from a completion or 
interrupt routine. 

Form: i = IGETC () 

Function Result: 

i = n Channel n has been allocated. 
Error: 

i = -1 No channels are available. 
Example: 

ICHAN=IGETC( ) ! ALLOCATE CHANNEL 

IF(ICHAN.LT.O) STOP 'CANNOT ALLOCATE CHANNEL' 

t 
i 

t 

CALL IFREEC( ICHAN) ! FREE IT WHEN THROUGH 



END 



3.28 IGETSP 



The IGETSP subroutine obtains free space from the FORTRAN system and 
returns the address and size (in number of words) of the allocated space. 
When this space is obtained, it is allocated for the duration of the program. 

Form: i = IGETSP (min,max,iaddr) 

where: 

min is the minimum space to be obtained without an error indicat- 
ing that the desired amount of space is not available 

max is the maximum space to be obtained 

iaddr is the integer specifying the address of the start of the free space 
(buffer). Note that iaddr does not directly denote the storage 
area as a standard FORTRAN variable would. Rather, it de- 
notes a word that contains the address of the storage space. It is 
most useful with IPEEK and IPOKE, or with assembly 
language subroutines 

NOTE 

Extreme caution should be exercised to avoid using all of the 

TRAN system runs out of dynamic free space, fatal errors 
(Error 29, 30, 42, and so forth) occur. See the RT-11 System 
Message Manual. 
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Function Results: 

i = n The actual size allocated whose value is min .LE. n .LE. max. 
The size {min, max, n) is specified in words. 

Error: 

i = -1 Not enough free space is available to meet the minimum re- 
quirements; no allocation was taken from the FORTRAN sys- 
tem free space. 

Example: 

N = IGETSP(Z56 .25G .IBUFF) ! GET 25B WORD BUFFER 

IF(N,LT.c3) STOP 'CANNOT GET BUFFER SPACE!' ! NO SPACE AMAILABLE 



3.29 IGTJB 

(See the SYSLIB subroutine GTJB.) 



3.30 IJCVT 



The IJCVT function converts an INTEGER*4 value to INTEGER*2 format. 
If ires is not specified, the result returned is the INTEGER*2 value of jsrc. If 
ires is specified, the result is stored there. 

Form: i = IJCVT (jsrc [, ires]) 

where: 

jsrc specifies the INTEGER*4 variable or array element whose value 
is to be converted 

ires specifies the INTEGER*2 entity to receive the conversion result 

Function Results (if ires is specified): 

i = -2 An overflow occurred during conversion. 

= -1 Normal return; the result is negative. 

= Normal return; the result is 0. 

= 1 Normal return; the result is positive. 

Errors: 

None. 
Example: 

INTEGER#a JVAL 
INTEGER#2 IMAL 



IF( IJCMT( JMAL tIMAL) .EO,-Z) TYPE 99 
39 FORMAK' NUHBER TOO LARGE IN IJCUT CONVERSION') 
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3.31 ILUN 



The ILUN function returns the RT-11 channel number with which a FOR- 
TRAN logical unit is associated. 

Form: i = ILUN (lun) 

where: 

lun is an integer expression whose value is a FORTRAN logical unit 
number in the range 1-99 

Function Results: 

= +n RT-11 channel number n is associated with lun. 

Errors: 

i = -1 Logical unit is not open. 
= -2 Logical unit is opened to console terminal. 

Example: 

PRINT 39 
99 FORMAT',' PRINT DEFAULTS TO LOGICAL UNIT G, WHICH FURTHER DEFAULTS TO LP:') 
ICHAN=ILUN(6) IWHICH RT-11 CHANNEL IS RECEIUING I/O? 



3.32 INDEX 



The INDEX subroutine searches a source string for the occurrence of a pat- 
tern string and returns the character position of the first occurrence of the 
pattern within the source. 

Form: CALL INDEX (a,pattrn,[i],m) 
or 
m = INDEX (a,pattrn[,i]) 



where: 



a is the array containing the source string to be searched; it 

must be terminated by a null byte 

pattrn is the string being sought; it must be terminated by a null byte 

i is the integer starting character position of the search in a. If i 

is omitted, a is searched beginning at the first character 
position 

m is an integer variable to store the result of the search; m is set 

to the starting character position of pattrn in a, if found; 
otherwise tn is 



Errors: 

None. 
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Example: 



The following example searches the array STRING for the first occur- 
rence of strings EFG and XYZ and searches the string ABCABCABC 
for the occurrence of string ABC after position 5. 

CALL SCOPY( 'ABCDEFGHI ' .STRING) UNITIALIZE STRING 

CALL INDE>;(STRING . 'EFG' . ,ri) !11 = 5 

CALL INDEX<STRING , 'XYZ' , tN) !N = 

CALL INDEX( 'ABCABCABC , 'ABC »5 .L) !L = 7 



3.33 INSERT 

The INSERT subroutine replaces a portion of one string with another string. 

Form: CALL INSERT (in,out4[,m]) 

where: 

in is the array containing the string being inserted. The string must 
be terminated with a null if the number of characters is less than 
the value of m (below), or if m is not specified 

out is the array containing the string being modified. The string must 
be terminated with a null 

i is the integer specifying the character position in out at which the 

insertion begins 

m is the integer maximum number of characters to be inserted 

If the maximum number of characters (m) is not specified, all characters to 
the right of the specified character position (i) in the string being modified are 
replaced by the string being inserted. The insert string {in) and the string 
being modified (out) can be in the same array only if the maximum number of 
characters (m) is specified and is less than or equal to the difference between 
the position of the insert (i) and the maximum string length of the array. 

Errors: 

None. 

Example: 

CALL SCOPY( 'ABCDEFGHIJ' ,Sn ! INITIALIZE STRING 1 

CALL SC0PY(S1,S2) ! INITIALIZE STRING 2 

CALL INSERT( '123' ,S1 »G.3) !S1 = 'ABCDE123IJ' 

CALL INSERT( '123' fS2 »a) ! SZ = 'ABC123' 



3.34 INTSET 



The INTSET function establishes a FORTRAN subroutine as an interrupt 
service routine, assigns it a priority, and attaches it to a vector. INTSET 



3-28 Sjfstem Subroutine Description and Examples 



requires that extra memory be allocated to foreground programs that use it 
(see Section 1.2.4.1). 

Form: i = INTSET (vect,pri,id,crtn) 



where: 



vect is the integer specifying the address of the interrupt vector to 
which the subroutine is to be attached 

pri is the integer specifying the actual priority level (4-7) at which 

LilC LiCVl«.-rT iiHyCix ui|J I/O 

id is the identification integer to be passed as the single argument 
to the FORTRAN routine when an interrupt occurs. This allows 
a single crtn to be associated with several INTSET calls 

crtn is a FORTRAN subroutine to be established as the interrupt 
routine. This name should be specified in an EXTERNAL state- 
ment in the FORTRAN program that calls INTSET. The sub- 
routine has one argument: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argument is 
the value specified for id in the appropriate INTSET call 

Notes: 

1. The id argument can be used to distinguish between interrupts from dif- 
ferent vectors if the routine to be activated services multiple devices. 

2. When using INTSET in FB or XM, the SYSLIB call DEVICE must be 
used in almost all cases to prevent interrupts from interrupting beyond 
program termination. 

3. If the interrupt routine {crtn) has control for a period of time longer than 
the time in which two more interrupts using the same vector occur, inter- 
rupt overrun is considered to have occurred. The error message: 

?SYSLIB-F-Interrupt overrun 

is printed and the job is aborted. Jobs requiring very fast interrupt re- 
sponse are not viable with FORTRAN, since FORTRAN overhead lowers 
RT-ll's interrupt response rate. 

4. The interrupt routine (crtn) is actually run as a completion routine by the 
RT-11 .SYNCH macro. The pri argument is used for the RT-11 .INTEN 
macro. 

5. A .PROTECT request is issued for the vector, but no attempt is made to 
report an error if the vector is already protected; furthermore, the vector is 
taken over unconditionally. See the .PROTECT programmed request 
(Section 2.55) for more information. 

6. The FORTRAN interrupt service subroutine {crtn) cannot call the USR. 
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7. INTSET cannot be called from a completion or interrupt routine. 

8. Interrupt enable should not be set on the associated device until the 
INTSET call has been successfully executed. 

Errors: 

i = Normal return. 

= 1 Invalid vector specification. 

= 2 Reserved for future use. 

= 3 No space is available for the linkage setup. 

Example: 

EXTERNAL CLKSUB ! SUBR TO HANDLE KWll-P CLOCK 



I = INTSET( "10a,B .O.CLKBUB) ! ATTACH ROUTINE 
IF (I.NE.O) GOTO 100 ! BRANCH IF ERROR 



END 

SUBROUTINE CLKBUB(ID) 



END 



3.35 IPEEK 



The IPEEK function returns the contents of the word located at a specified 
absolute 16-bit memory address. This function can examine device registers or 
any location in memory. 

Form: i = IPEEK (iaddr) 

where: 

iaddr is the integer specification of the absolute address to be 
examined. If this argument is not an even value, a trap results 
(except on LSI-11 or a PDP-11/23) 

Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 

ISWIT = IPEEK("177570) ! GET UALUE OF CONSOLE SWITCHES 



3.36 IPEEKB 



The IPEEKB subroutine returns the contents of a byte located at a specified 
absolute byte address. Since this routine operates in a byte mode, the address 
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supplied can be odd or even. This subroutine can examine device registers or 
any byte in memory. The return is zero extended, that is, the high byte is 0. 

Form: i = IPEEKB (iaddr) 

where: 

iaddr is the integer specification of the absolute byte address to be 
examined. Unlike the IPEEK subroutine, the IPEEKB subrou- 
tine allows odd addresses 

Function Result: 

The function result (i) is set to the value of the byte examined. 

Example: 

I ERR = IPEEKB ("53) !Get error byte 



3.37 IPOKE 

The IPOKE subroutine stores a specified 16-bit integer value into a specified 
absolute memory location. This subroutine can store values in device 
registers. 

Form: CALL IPOKE (iaddr, ivalue) 
where: 

iaddr is the integer specification of the absolute address to be modi- 
fied. If this argument is not an even value, a trap results 
(except on LSI-11 or PDP-11/23) 

ivalue is the integer value to be stored in the given address specified 
by the iaddr argument 

Errors: 

None. 

Example: 

The following example displays the value of IVAL in the console display 
register (this is possible only on certain processors). 

CALL IPOKE( " 177570 ,IUAL) 

To set bit 12 in the JSW without zeroing any other bits in the JSW, use 
the following procedure. 

CALL I POKE ("44 ("10000, OR. I PEEK ( "44) ) 



3.38 IPOKEB 

The IPOKEB subroutine stores a specified eight-bit integer value into a speci- 
fied byte location. Since this routine operates in a byte mode, the address 
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supplied can be odd or even. This subroutine can store values in device 
registers. 

Form: CALL IPOKEB (iaddr,ivalue) 
where: 

iaddr is the integer specification of the absolute address to be modi- 
fied. Unlike the IPOKE subroutine, the IPOKEB subroutine 
allows odd addresses 

lvalue is the integer value to be stored in the given address specified 
by the iaddr argument 

Errors: 

None. 

Example: 

CALL IPOKEB( "53 t"20) ! Tell KMON un con d i t i or,a 1 1 y fatal error 



3.39 IQSET 



The IQSET function is used to make the RT-11 I/O queue larger — that is, 
to add available elements to the queue. These elements are allocated out of 
the free space managed by the FORTRAN system. IQSET cannot be called 
from a completion or interrupt routine. 

Form: i = IQSET (qleng[,area]) 

where: 

qleng is the integer number of elements to be added to the queue. 
This argument must be positioned so that the USR does not 
swap over it 

area is the space allocated from within the calling program. Under 
FB and SJ monitors, make sure that the space is outside the 
USR swapping area. If this argument is not specified, the space 
for the elements is allocated in the FORTRAN OTS work area 

All RT-11 I/O transfers are done through a centralized queue management 
system. If I/O traffic is very heavy and not enough queue elements are avail- 
able, the program issuing the I/O requests is suspended until a queue element 
becomes available. In an FB or XM system, the other job can run while the 
first program waits for the element. When IQSET is used in a program to be 
run in the foreground, the FRUN command must be modified to allocate 
space for the queue elements (see Section 1.2.4.1). 

A general rule to follow is that each program. should contain one more queue 
element than the total number of I/O and timer requests that will be active 
simultaneously. Timing functions such as ITWAIT and MRKT also cause 
elements to be used and must be considered when allocating queue elements 
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for a program. Note that if synchronous I/O is done (for example, 
IREADW/IWRITW) and no timing functions are done, no additional queue 
elements need be allocated. Note also that FORTRAN IV allocates four queue 
elements by default. 

The following subroutines require queue elements: 

IRCVDARCVDC/IRCVDF/IRCVDW ITIMER 

IREAD/IREADC/IREADFAREADW ITWAIT 

ISCHED lUNTIL 

ISDAT/ISDATCASDATF/ISDATW IWRITE/IWRITCAWRITF/IWRITW 

ISLEEP IVIRKT 

ISPFNASPFNCASPFNF/ISPFNW MWAIT 

For further information on adding elements to the queue, see the .QSET 
programmed request. 

Errors: 

i = Normal return. 
= 1 Not enough free space is available for the number of queue 
elements to be added; no allocation was made. 

Example: 

IF( I03ET(5) .NE.O) STOP 'NOT ENOUGH FREE SPACE FOR QUEUE ELEMENTS' 



3.40 IRAD50 



The IRAD50 function converts a specified number of ASCII characters to 
Radix-50 and returns the number of characters converted. Conversion stops 
on the first non-Radix-50 character encountered in the input, or when the 
specified number of ASCII characters have been converted. 

Form: n = IRAD50 (icnt, input, output) 

where: 

n is the integer number of input characters actually connected 

icnt is the number of ASCII characters to be converted 

input is the area from which input characters are taken 
output is the area in which Radix-50 words are stored 

Three characters of text are packed into each word of output. The number of 
output words modified is computed by the expression (in integer words): 

(icnt+2)/3 

Thus, if a count of 4 is specified, two words of output are written even if only a 
one-character input string is given as an argument. 
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Function Result: 

The integer number of input characters actually converted (n) is returned as 
the function result. 

Example: 

REAL*B FSPEC 

CALL IRAD50(1Z, 'SYOTEMP DAT'. FSPEC) 



3.41 IRCVD/IRCVDC/IRCVDF/IRCVDW (FB and XM Only) 

There are four forms of the receive data function; these are used in conjunc- 
tion with the ISDAT (send data) functions to allow a general data/message 
transfer system. The receive data functions issue RT-11 receive data pro- 
grammed requests (see Section 2.60). These functions require a queue 
element; this should be considered when the IQSET function (Section 3.39) is 
executed. 

IRCVD 

The IRCVD function receives data and continues execution. The operation is 
queued and the issuing job continues execution. When the job has to receive 
the transmitted message, an MWAIT should be executed. This causes the job 
to be suspended until the message has been received. 

Form: i = IRCVD (buff, went) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVD is complete 

went is the maximum integer number of words that can be received 

Errors: 

i = Normal return. 
= 1 No such job exists in the system. 

Example: 

INTEGER*2 MSG(ill) 



CALL IRCVD ( MSG »ilO) 



CALL MNAIT 

IRCVDC 

The IRCVDC function receives data and enters an assembly language comple- 
tion routine when the message is received. The IRCVDC is queued, and 
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program execution stays with the issuing job. When the other job sends a 
message, the completion routine specified is queued and run according to 
standard scheduhng of completion routines. 

Form: i = IRCVDC (buff,wcnt,crtn) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received because 
the first word contains the integer number of words actually 
transmitted when IRCVDC is complete 

went is the maximum integer number of words to be received 

crtn is the assembly language completion routine to be entered. This 
name must be specified in a FORTRAN EXTERNAL statement 
in the routine that issues the IRCVDC call 



Errors: 



i = Normal return. 
= 1 No such job exists in the system. 



IRCVDF 

The IRCVDF function receives data and enters a FORTRAN completion sub- 
routine when the message is received. The IRCVDF is queued, and program 
execution continues with the issuing job. When the other job sends a message, 
the FORTRAN completion routine specified is entered. 

Form: i = IRCVDF (buff,wcnt,area,crtn) 
where: 

must be one word larger than the message to be received because 
the first word contains the integer number of words actually 
transmitted when IRCVDF is complete 

went is the maximum integer number of words to be received 

area is a four-word area to be set aside for linkage information. This 
area must not be modified by the FORTRAN program and the 
USR must not swap over it. This area can be reclaimed by other 
FORTRAN completion routines when crtn has been entered 

crtn is the FORTRAN completion routine to be entered. This name 
must be specified in an EXTERNAL statement in the 
FORTRAN routine that issues the IRCVDF call 



iirrors: 



Normal return. 

1 No such job exists in the system. 
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Example: 



INTEGER*Z MSG(41 ) ,AREA(4) 
EXTERNAL RHSGRT 



CALL IRCMDFCMSG ,40 ,AREA tRMSGRT: 



IRCVDW 

The IRCVDW function receives data and waits. This function queues a mes- 
sage request and suspends the job issuing the request until the other job sends 
a message. When execution of the issuing job resumes, the message has been 
received, and the first word of the buffer indicates the number of words 
transmitted. 

Form: i = IRCVDW (buff, went) 

where: 

buff is the array to be used to buffer the data received. The array 
must be one word larger than the message to be received 
because the first word contains the integer number of words 
actually transmitted when IRCVDW is complete 

went is the maximum integer number of words to be received 
Errors: 

i = Normal return. 
= 1 No such job exists in the system. 

Example: 

INTEGER#2 MBG(41 ) 

IF( IRCVDW(MBG ,40) . NE.O) STOP 'UNEXPECTED ERROR' 



3.42 IREAD/IREADC/IREADF/IREADW 

The functions IREAD, IRE ADC, IREADF, and IREADW transfer a specified 
number of words from a file into memory. These functions require a queue 
element, which should be considered when the IQSET function (Section 3.39) 
is executed. 

IREAD 

The IREAD function transfers into memory a specified number of words from 
the file associated with the indicated channel. Control returns to the user 
program immediately after the IREAD function is initiated. No special action 
is taken when the transfer is completed. 
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Form: i = IREAD (wcnt,buff,blk,chan) 

where: 

went is the relative integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain at 
least went words 

blk is the relative integer block number of the file to be read. The 
first block of a file is block number 0. The blk argument must be 
updated when necessary. For example, if the program is reading 
two blocks at a time, blk should be updated by 2 

chan is the relative integer specification for the RT-11 channel to be 
used 

When the user program needs to access the data read on the specified chan- 
nel, an IWAIT function should be issued. This makes sure that the IREAD 
operation has been completed. If an error occurred during the transfer, the 
IWAIT function indicates the error. 



Errors: 



= n Normal return; n equals the number of words requested (0 for 
non-file-structured read, multiple of 256[decimal] for file-struc- 
tured read). If the read is from a magtape, the number of words 
requested is returned. For example: 

If went is a multiple of 256 and less than that number of 
words remain in the file, n is shortened to the number of 
words that remain in the file; thus, if went is 512 and only 
256 words remain, i = 256. 

If went is not a multiple of 256 and more than went words 
remain in the file, n is rounded up to the next block; thus, if 
went is 312 and more than 312 words remain, i = 512, but 
only 312 are read. 

If went is not a multiple of 256 and less than went words 
remain in the file, n equals a multiple of 256 that is the 
actual number of words being read. 

= -1 Attempt to read past end-of-file; no words remain in the file. 
= -2 Hardware error occurred on channel. 
= -3 Specified channel is not open. 

NOTE 

If an asynchronous operation on a channel (for example, 
IREAD) results in end-of-file, the following IWAIT will not 
detect it. IWAIT detects only hard error conditions. A subse- 
quent operation on that channel will detect end-of-file and re- 
turns to the user with the end-of-file error code. Under these 
conditions, the subsequent operation is not initiated. 
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Example: 

INTEGER*2 BUFFER(25S) ,RCODE .BLK 



RCODE = IREAD(25G tBUFFER tBLK ,ICHAN) 

I F ( RCODE+ 1 ) 1 1 f 1 000 , 1 
C IF NO ERROR, START HERE 
10 



IF( IWAIT(ICHAN) ,NE,0) GOTO 1010 



1000 CONTINUE 

C END OF FILE PROCESSING 



CALL EXIT ! NORMAL END OF PROGRAM 

1010 STOP 'FATAL READ' 
END 



IREADC 

The IREADC function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program immediately 
after the IREADC function is initiated. When the operation is complete, the 
specified assembly language routine (crtn) is entered as an asynchronous 
completion routine. 

Form: i = IREADC (wcnt,buff,blk,chan,crtn) 
where: 

went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain at 
least went words 

blk is the integer block number of the file to be read. The user 
program normally updates blk before it is used again. The first 
block of a file is block number 

chan is the integer specification for the RT-11 channel to be used 

crtn is the assembly language routine to be activated when the trans- 
fer is complete. This name must be specified in an EXTERNAL 
statement in the FORTRAN routine that issues the IREADC 
call 

Errors: 

See the errors under IRE AD. 
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Example: 



INTEGER*2 IBUF(25B) tRCODE»IBLK 
EXTERNAL RDCMP 



RC0DE=IREADC(25G,IBUF .IBLK » I CHAN f RDCMP) 



IREADF 

The IREADF function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program immediately 
after the IREADF function is initiated. When the operation is complete, the 
specified FORTRAN subprogram (crtn) is entered as an asynchronous com- 
pletion routine (see Section 1.2.1.2). 

Form: i = IREADF (wcnt,buff,blk,chan,area,crtn) 



where: 



went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain at 
least went words 

blk is the integer block number of the file to be used. The user 
program normally updates blk before it is used again. The first 
block of a file is block number 

chan is the integer specification for the RT-11 channel to be used 

area is a four- word area to be set aside for link information; this area 
must not be modified by the FORTRAN program or swapped 
over by the USR. This area can be reclaimed by other FOR- 
TRAN completion functions when crtn has been activated 

crtn is the FORTRAN routine to be activated on completion of the 
transfer. This name must be specified in an EXTERNAL state- 
ment in the routine that issues the IREADF call. Section 1.2.1.2 
describes completion routines 



Errors: 



See the errors under IREAD. 



Example: 



INTEGER*2 DBLK ( il ) ,BUFFERC25B) »BLKND 

DATA DBLK/3RDX0 .3RINP .3RUT ,3RDAT / »BLKNO/0/ 

EXTERNAL RCMPLT 



ICHAN = IGETC( ) 

IF( ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 
IF( IFETCH(DBLK) .NE.O) STOP 'BAD FETCH' 
IF(LOOKUP(ICHAN »DBLK) .LT.O) STOP 'BAD LOOKUP' 
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20 IF(IREADF(25B .BUFFER ,BLKNO tlCHAN .DBLK »RCMPLT) .LT.rs) GOTO 100 
C PERFORM DMERLAP PROCESSING 



SYNCHRONIZER 
CALL IWAITdCHANl 
BLKN0=BLKN0+1 
GOTO 20 



IWAIT FOR COMPLETION ROUTINE TO RUN 
! UPDATE BLOCK NUMBER 



C END OF FILE PROCESSING 
100 CALL ICLOSE( ICHAN.I) 

I = ICLOSE( ) 

CALL IFREEC( ICHAN) 



CALL EXIT 

END 

SUBROUTINE RCMPLT( I .J) 

THIS IS THE COMPLETION ROUTINE 



RETURN 
END 



IREADW 

The IREADW function transfers a specified number of words from the indi- 
cated channel into memory. Control returns to the user program when the 
transfer is complete or when an error is detected. 

Form: i = IREADW (wcnt,buff,blk,chan) 
where: 

went is the integer number of words to be transferred 

buff is the array to be used as the buffer; this array must contain at 
least went words 

blk is the integer block number of the file to be read. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used 
Errors: 

See the errors under IREAD. 
Example: 

INTEGER*Z IBUF( 102^1) 
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IC0DE=IREADW(10Z4 tIBUF .IBLK » I CHAN) 

IF< ICODE.EO.-l) GOTO 100 ! END OF FILE PROCESSING AT 100 

IF( IC0DE,LT.-1) GOTO ZOO [ERROR PROCESSING AT 200 

C 

C MODIFY BLOCKS 

C 



C 

C WRITE THEM OUT 

C 



ICODE=IWRITW( 1024 » I BUF . IBLK , ICHAN ) 



3.43 IRENAM 



The IRENAM function causes an immediate change of the name of a speci- 
fied file. 

Form: i = IRENAM (chan,dblk) 

where: 

chan is the integer specification for the RT-11 channel to be used for 
the operation. You must obtain this channel through an IGETC 
call, or you can use channel 16(decimal) or higher if you have 
done an ICDFN call. The channel is again available for use once 
the rename operation is completed 

dblk is the eight-word area specifying the name of the existing file 
and the new name to be assigned. If considered as an eight- 
element INTEGER*2 array, dblk has the form: 

Words 1-4 specify the Radix-50 file descriptor for the old 
lUe name 

Words 5-8 specify the Radix-50 file descriptor for the new 
file name 



NOTE 

The arguments of IRENAM must be positioned so that the 
USR does not swap over them. 

If a file already exists with the same name as the new file on the indicated 
device, it is deleted. IRENAM requires that the handler to be used be resident 
at the time the IRENAM is issued. If it is not, a monitor error occurs. The 

For more information on renaming files, see the .RENAME programmed re- 
quest (Section 2.65). 
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Errors: 



Normal return. 

1 Specified channel is already open. 

2 Specified file was not found. 

3 A file by that name already exists and is protected. 



Example: 



REAL*8 NAME(2) 

DATA NAME/12RDK0FTN: 



DAT .12RDK0FTN: 



OLD/ 



ICHAN=IGETC( ) 
IFf ICHAN.LT.O) STOP 'NO 
CALL IRENAMdCHANfNAME) 
CALL IFREEC( ICHAN) 



CHANNEL' 
! FREE 



ERUE OLD DATA FILE 



3.44 IREOPN 



The IREOPN function reassociates a specified channel with a file on which an 
ISAVES was performed. The ISAVES/IREOPN combination is useful when a 
large number of files must be operated on at one time. Necessary files can be 
opened with LOOKUP and their status preserved with ISAVES. When data is 
required from a file, an IREOPN enables the program to read from the file. 
The IREOPN need not be done on the same channel as the original LOOKUP 
and ISAVES. 

Form: i = IREOPN (chan,cblk) 

where: 



chan 



cblk 



Errors: 



is the integer specification for the RT-11 channel to be 
associated with the reopened file; this channel must be initially 
inactive 

is the five-word block where the channel status information was 
stored by a previous ISAVES. This block, considered as a five- 
element INTEGER*2 array, has the following format: 

Word 1 Channel status word. 

2 Starting block number of the file; zero for non-file- 
structured devices. 

3 Length of file (in 256- word blocks). 

4 Reserved for future use. 

5 Two information bytes. Even byte: I/O count of the 
number of requests outstanding on this channel. 
Odd byte: unit number of the device associated with 
the channel. 



Normal return. 

1 Specified channel is already in use. 
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Example: 



INTEGER*2 BAyES<5 ,10) 
DATA IBUPTR/1/ 



CALL ISAUESC ICHAN tSAvESC 1 jISvPTR) 



CALL IREOPNC ICHAN .SAMESC 1 ,ISyPTR) ) 



3.45 ISAVES 



The ISAVES function stores five words of channel status information into a 
user-specified array. These words contain all the information that RT-11 
requires to completely define a file. When an ISAVES is finished, the data 
words are placed in memory and the specified channel is closed, so that it is 
again available for use. When the saved channel data is required, the 
IREOPN function (Section 3.44) is used. 

ISAVES can be used only if a file was opened with a LOOKUP call (see 
Section 3.74). If lENTER was used, ISAVES returns an error. Note that 
ISAVES is not legal on magtape or cassette files. 

Form: i = ISAVES (chan,cblk) 

where: 

chan is the integer specification for the RT-11 channel whose status 
is to be saved. You must obtain this channel through an IGETC 
call, or you can use channel 16 or higher if you have done an 
ICDFNcall 

cblk is a five-word block in which the channel status information 
describing the open file is stored (see Section 3.44 for the format 
of this block). 

The ISAVES/IREOPN combination is very useful, but care must be exercised 
when using it. In particular, the following cases should be avoided. 

1. If an ISAVES is performed on a file and the same file is then deleted 
before it is reopened, the space occupied by the file becomes avail- 
able as an empty space which could then be used by the lENTER 
function. If this sequence occurs, there is a change in the contents of 
the file whose status was supposedly saved. 

2. Although the handler for the required peripheral need not be in 
memory for execution of an IREOPN, a fatal error is generated if the 
handler is not in memory when an IREAD or IWRITE is executed. 
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Errors: 

i = Normal return. 
= 1 The specified channel is not currently associated with any file. 
= 2 The file was opened with an lENTER call. 

Example: 

INTEGER*2 BLK(5) 

t 
t 

IF( ISAUES( ICHANfBLK) .NE,0) STOP 'ISAUES ERROR' 



3.46 ISCHED 



The ISCHED function schedules a specified FORTRAN subroutine to be run 
as an asynchronous completion routine at a specified time of day. Support for 
ISCHED in SJ also requires timer support. 

Form: i = ISCHED {hrs,min,sec,tick,area,id,crtn) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

area is a four- word area that must be provided for link information; 
this area must never be modified by the FORTRAN program, 
and the USR must not swap over it. This area can be reclaimed 
by other FORTRAN completion functions when crtn has been 
activated 

id is the identification integer to be passed to the routine being 
scheduled 

crtn is the name of the FORTRAN subroutine to be entered at the 
time of day specified. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISCHED call. The subroutine has one argument. For 
example: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argument is 
the value specified for id in the appropriate ISCHED call 
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Notes: 

1. The scheduling request made by ISCHED can be canceled at a later time 
by an ICMKT function call. 

2. If the system is busy, the actual time of day that the completion routine is 
run may be later than the requested time of day. 

3. A FORTRAN subroutine can periodically reschedule itself by issuing its 
own ISCHED or ITIMER calls from within the routine. 
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IQSET function (Section 3.39) is executed. 

Errors: 

i = Normal return. 
= 1 No queue elements available; unable to schedule request. 

Example: 



II\|TEGER*2 LINK(a) 
EXTERNAL NDON 



! LINKAGE AREA 

! NAME OF ROUTINE TO RUN 



!RUN SUBR NOON AT 12 PM 



I = IBCHED(12 jO tO .0 .LINK ,0 (NOON) 

« 

, (rest of main program) 

END 

SUBROUTINE NOON( ID) 



THIS ROUTINE WILL TERMINATE EXECUTION AT LUNCHTIME 
IF THE JOB HAS NOT COMPLETED BY THAT TIME. 



STOP 
END 



'ABORT JOB -- LUNCHTIME'- 



3.47 ISCOMP 

(See SYSLIB subroutine SCOMP.) 



3.48 ISDAT/ISDATC/ISDATF/ISDATW (FB and XM Only) 

The functions ISDAT, ISDATC, ISDATE, and ISDATW are used with the 
IRCVD/IRCVDC/IRCVDF, and IRCVDW calls to allow message transfers 
under the FB or XM monitor. Note that the buffer containing the message 
should not be modified or reused until the message has been received by the 
other job. These functions require a queue element, which should be consid- 
ered when the IQSET function (see Section 3.39) is executed. 

ISDAT 

The ISDAT function transfers a specified number of words from one job to the 
other. Control returns to the user program immediately after the transfer is 
queued. This call is used with the MWAIT routine (see Section 3.85). 
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Form: i = ISDAT (buff, went) 

where: 

buff is the array containing the data to be transferred 
went is the integer number of data words to be transferred 

Errors: 

i = Normal return. 
= 1 No such job currently exists in the system. 

Example: 

INTEGER*2 MBG(flO) 
CALL ISDAT{MSG.40) 



CALL HNAIT 
C PUT NEW MESSAGE IN BUFFER 

ISDATC 

The ISDATC function transfers a specified number of words from one job to 
another. Control returns to the user program immediately after the transfer is 
queued. When the other job accepts the message through a receive data 
request, the specified assembly language routine (crtn) is activated as an 
asynchronous completion routine. 

Form: i = ISDATC (buff,wcnt,crtn) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

crtn is the name of an assembly language routine to be activated on 
completion of the transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISDATC call 



Errors: 



i = Normal return. 
= 1 No such job currently exists in the system. 



Example: 



INTEGER#2 MSG(aO) 
EXTERNAL RTN 



CALL ISDATCCMSG .40 ,RTN) 
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ISDATF 

The ISDATF function transfers a specified number of words from one job to 
the other. Control returns to the user program immediately after the transfer 
is queued and execution continues. When the other job accepts the message 
through a receive data request, the specified FORTRAN subprogram (crtn) is 
activated as an asynchronous completion routine (see Section 1.2.1.2). 

Form: i = ISDATF (buff, wcnt,area, crtn) 

where: 

buff is the array containing the data to be transferred 

went is the integer number of data words to be transferred 

area is a four-word area to be set aside for link information; this area 
must not be modified by the FORTRAN program and the USR 
must not swap over it. This area can be reclaimed by other 
FORTRAN completion functions when crtn has been activated 

crtn is the name of a FORTRAN routine to be activated on comple- 
tion of the transfer. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISDATF call 



Errors: 



i = Normal return. 
= 1 No such job currently exists in the system. 



Example: 



INTEGER*2 MSG ( ilO ) ,SPDT ( 4 ) 
EXTERNAL RTN 



CALL ISDATF(MSG »ilO fSPOT ,RTN) 



ISDATW 

The ISDATW function transfers a specified number of words from one job to 
the other. Control returns to the user program when the other job has ac- 
cepted the data through a receive data request. 

Form: i = ISDATW (buff, went) 

where: 

buff is the array containing the data to be transferred 
went is the integer number of data words to be transferred 



Mirrors: 



Normal return. 

1 No such job currently exists in the system. 
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Example: 

INTEGER*Z MSG(ilO> 

IF ( ISDATW(MSG ,40) .NE.O) STOP 'FOREGROUND JOB NOT RUNNING 



3.49 ISLEEP 



The ISLEEP function suspends the main program execution of a job for a 
specified amount of time. The specified time is the sum of hours, minutes, 
seconds, and ticks specified in the ISLEEP call. All completion routines con- 
tinue to execute. 

Form: i = ISLEEP (hrs,min,sec,tick) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60- cycle clocks; 
1/50 of a second on 50-cycle clocks) 

Notes: 

1. SLEEP requires a queue element, which should be considered when the 
IQSET function (Section 3.39) is executed. 

2. If the system is busy, the time in which execution is suspended may be 
later than that specified. 

Errors: 

i = Normal return. 
= 1 No queue element available. 

Example: 



CALL IQSET(2) 



CALL ISLEEPiO ,0 ,0 ,4) !GIUE BACKGROUND JOB SOME TIME 



3.50 ISPFN/ISPFNC/ISPFNF/ISPFNW 

The functions ISPFN, ISPFNC, ISPFNF, and ISPFNW are used in conjunc- 
tion with special functions to various handlers. They provide a means of doing 
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device-dependent functions, such as rewind and backspace, to those devices. 
If ISPFN function calls are made to any other devices, the function call is 
ignored. For more information on programming for specific devices, see the 
RT-11 Software Support Manual. 

To use these functions, the handler must be in memory, and a channel must 
be associated with a file via a non-file-structured LOOKUP call. These func- 
tions require a queue element; this should be considered when the IQSET 
function (Section 3.39) is executed. 

ISPFN 

The ISPFN function queues the specified operation and immediately returns 
control to the user program. The IWAIT function can be used to ensure 
completion of the operation. 

Form: i = ISPFN (code,chan[,wcnt,buff,blk]) 

where: 



code is the integer numeric code of the function to be performed (see 
Table 3-1) 

chan is the integer specification for the RT-11 channel to be used for 
the operation. You must obtain this channel through an IGETC 
call, or you can use channel 16 (decimal) or higher if you have 
done an ICDFN call 

went is the integer number of data words in the operation. This 
parameter is optional with some ISPFN calls, depending on the 
particular function. Default value is 0. In magtape operations, it 
specifies the number of records to space forward or backward. 
For a backspace operation {wcnt=Q), the tape drive backspaces 
to a tape mark or to the beginning-of-tape. For a forward space 
operation {wcnt=0), the tape drive forward spaces to a tape 
mark or the end-of-tape 

buff is the array to be used as the data buffer. This parameter is 
optional with some ISPFN calls, depending on the particular 
function. Default value is 

blk is the integer block number of the file to be operated upon. This 
parameter is optional with some ISPFN calls, depending on the 
particular function. Default value is 0. 

When this argument is supplied by magtape, it is the address of 
a four-word error and status block used for returning the excep- 
tion conditions. The four words must be initialized to zero. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. To 
obtain the address of the error block execute the followin*^ 
instructions: 



INTEGER*2 
DATA ERRBLK 



ERRADR . ERRBLK (a) 
/ 1 1 f t / 
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ERRADR = lADDR (ERRBLK) 

!GET THE ADDRESS OF THE a-WORD ERROR BLOCK 

ICODE = ISPFN (CODE ..ICHAN tWDCT .BUF .ERRADR) 

The three optional arguments (went, buff, blk) are not individually optional. 
You must have all or none present. 

Table 3-1: Functions and Function Codes (Octal) 



Function 


MT.MM 


CT 


DX 


DM 


DY 


DL 


Read absolute 






377 


377 


377 


377 


Write absolute 






376 


376 


376 


376 


Write absolute with 














deleted data 






375 




375 




Forward to last file 




377 










Forward to last block 




376 










Forward to next file 




375 










Forward to next block 




374 










Rewind to load point 


373 


373 










Write file gap 




372 










Write end-of-file 


377 












Forward 1 block 


376 












Backspace 1 block 


375 












Initialize the bad 














block replacement table 








374 




374 


Write with extended 














record gap 


374 












Offline 


372 












Return volume size 








373 


373 


373 


Write variable size blocks 


371 












Read variable size blocks 


370 













Errors: 



= 

= 1 
= 2 
= 3 



Normal return. 

Attempt to read or write past end-of-file. 
Hardware error occurred on channel. 
Channel specified is not open. 



iple: 



CALL ISPFN("373 fICHAN) 



[REWIND 



ISPFNC 

The ISPFNC function queues the specified operation and immediately 
returns control to the user program. When the operation is complete, the 
specified assembly language routine {crtn) is entered as an asynchronous com- 
pletion routine. 



Form: 
where: 



code 



ISPFNC (code,chan,wcnt,buff,blk,crtn) 



is the integer numeric code of the function to be performed (see 
Table 3-1) 
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chan is the integer specification for the RT-11 channel to be used for 
the operation. You must obtain this channel through an IGETC 
call, or you can use channel 16 (decimal) or higher if you have 
done an ICDFN call 

went is the integer number of data words in the operation; the default 
value for this argument is 

buff is the array to be used as the data buffer; the default value for 
this argument is 



V.1V 



io fVjQ inte'^'er block number of the file to be c^erated u^on' this 
argument must be if not required. 

When this argument is supplied by magtape, it is the address of 
a four-word error and status block used for returning the excep- 
tion conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. To 
obtain the address of the error block execute the following 
instructions: 



INTEGER*2 
DATA ERRBLK 



ERRADR. ERRBLK (4) 
/ 1 1 » f / 



!GET ADDRESS OF fl-WORD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = ISPFNC (CODE tlCHAN .WDCT ,BUF »ERRADR) 

crtn is the name of an assembly language routine to be activated on 
completion of the operation. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISPFNC call 



terrors: 

i = 

= 1 

= 2 

= 3 

Example: 



Normal return. 

Attempt to read or write past end-of-file. 
Hardware error occurred on channel. 
Channel specified is not open. 



EXTERNAL SFCOMP 



INAME OF ASSEMBLY LANGUAGE COMPLETION RTN 



ICODE = ISPFNC(CODE .ICHAIM ,WDCT ,BUF»BLK »SFCOMP) 

ISPFNF 

The ISPFNF function queues the specified operation and immediately returns 

control to the user program. When the operation is complete, the specified 

FORTRAN subprogram (crtn) is entered as an asynchronous completion 

routine. 
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Form: i = ISPFNF (code,chan,wcnt,buff,blk,area,crtn) 
where: 

code is the integer numeric code of the function to be performed (see 
Table 3-1) 

chan is the integer specification for the RT-11 channel to be used for 
the operation. You must obtain this channel through an IGETC 
call, or you can use channel 16(decimal) or higher if you have 
done an ICDFN call 

went is the integer number of data words in the operation; this argu- 
ment must be if not required 

buff is the array to be used as the data buffer; this argument must be 
if not required 

blk is the integer block number of the file to be operated upon; this 
argument must be if not required. 

When this argument is supplied by magtape, it is the address of 
a four-word error and status block used for returning the excep- 
tion conditions. The four words must be initialized to 0. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. To 
obtain the address of the error block, execute the following in- 
structions: 



INTEGER*2 
DATA ERRBLK 



ERRADR » ERRBLK(il) 
/ 1 > 1 » / 



!GET THE ADDRESS OF THE 4-WORD ERROR BLOCK 

ERRftDR = lADDR < ERRBLK) 

ICODE = ISPFNF (CODE fICHAN tWDCT .BUF .ERRADR) 

area is a four- word area to be set aside for linkage information; this 
area must not be modified by the FORTRAN program, and the 
USR must not swap over it. This area can be reclaimed by other 
FORTRAN completion functions when crtn has been activated 

crtn is the name of a FORTRAN routine to be activated on comple- 
tion of the operation. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the ISPFNF call (Section 1.2.1.2 describes completion 
routines) . 



Errors: 



Normal return. 

1 Attempt to read or write past end-of-file. 

2 Hardware error occurred on channel. 

3 Channel specified is not open. 
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Example: 



REAL*fl MTNAMEC2) »AREA(2) 
DATA MTNAME/3RMT0 »0,/ 
EXTERNAL DQNSUB 



I=IGETC() lALLOCATE CHANNEL 

CALL IFETCHCMTNAHE) ! FETCH MT HANDLER 

CALL LOOKUPCI »MTNAME) ! NON-FILE-STRUCTURED LOOKUP ON MTO 

IERR = ISPFNF( "373 »I .0 »0 »0 tAREA tOONSUD) IREWIND MAGTAPE 



END 

SUBROUTINE DQNSUB 

RUNS WHEN MTO HAS BEEN REWOUND 



END 



ISPFNW 

The ISPFNW function queues the specified operation and returns control to 

the user program when the operation is complete. 

Form: i = ISPFNW (code,chan[,wcnt,buff,blk!) 

where: 

code is the integer numeric code of the function to be performed (see 
Table 3-1) 

chan is the integer specification for the RT-U channel to be used for 
the operation. You must obtain this channel through an IGETC 

can, ur yuu Can use tnamiei ±uv.Liei;iiuai; Oi nigncl n yOu nave 

done an ICDFN call 

went is the integer number of data words in the operation. This 
parameter is optional with some ISPFNW calls, depending on 
the function 

buff is the array to be used as the data buffer. This parameter is 
optional with some ISPFNW calls, depending on the function 

blk is the integer block number of the file to be operated upon. This 
parameter is optional with some ISPFNW calls, depending on 
the function. 

When this argument is supplied by magtape, it is the address of 
a four-word error and status block used for returning the excep- 
tion conditions. The four worus must uB initiaiizeu to u. 

The error and status block must always be mapped when run- 
ning in the XM monitor, and the USR must not swap over it. To 
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obtain the address of the error block execute the following in- 
structions: 

IIMTEGER#2 ERRADR , ERRBLK(4) 
DATA ERRBLK /OtO»0,0,/ 



!GET THE ADDRESS OF THE -a-WORD ERROR BLOCK 

ERRADR = lADDR (ERRBLK) 

ICODE = IBPFN (CODE tICHAN tWDCT ,BUF , ERRADR) 

Errors: 

i = Normal return. 

= 1 Attempt to read or write past end-of-file. 

= 2 Hardware error occurred on channel. 

= 3 Channel specified is not open. 



Example: 



INTEGER*2 BUF(G5) tTRACK .SECTOR ,DBLK(a) 
DATA DBLK/3RDX0 ,0 .0 fO/ 



ICHAN=IGETC( ) 

IF(ICHAN.LT.O) STOP 'NO CHANNEL AVAILABLE' 

IF(LOOKUP( ICHAN.DBLK) .LT.O) STOP 'BAD LOOKUP' 



C READ AN ABSOLUTE TRACK AND SECTOR FROM THE FLOPP^i 
C 

IC0DE=I5PFNW("377 . 1 CHAN .TRACK »BUF .SECTOR) 
C 

C BUF(l) IS THE DELETED DATA FLAG 
C BUF(2-B5) IS THE DATA 



3.51 ISPY 



The ISPY function returns the integer value of the word at a specified offset 
from the RT-11 resident monitor. This subroutine uses the .GVAL pro- 
grammed request to return fixed monitor offsets. (See the RT-11 Software 
Support Manual for information on fixed offset references.) 

Form: i = ISPY (ioff) 

where: 

ioff is the offset (from the base of RMON) to be examined 
Function Result: 

The function result (i) is set to the value of the word examined. 

Example: 

c 

C BRANCH TO 200 IF RUNNING UNDER FB MONITOR 
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IF( ISPY( "300) . AND, 1) GOTO 200 
C 

C WORD AT OCTAL 300 FROM RMON IS 
C THE CONFIGURATION WORD, 



3.52 ITIMER 



The ITIMER function schedules a specified FORTRAN subroutine to be run 
as an as^^nchronous comT^letion routine after a specified time interval has 
elapsed. This request is supported by SJ when the timer support special 
feature is included during system generation. 

Form: i = ITIMER (hrs,min,sec,tick,area,id,crtn) 

where: 

hrs is the integer number of hours 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60- cycle 
clocks; 1/50 of a second on 50-cycle clocks) 

area is a four-word area that must be provided for link information; 
this area must never be modified by the FORTRAN program, 
and the USR must never swap over it. This area can be re- 
claimed by other FORTRAN completion functions when crtn 
has been activated 

id is the identification integer to be passed to the routine being 
scheduled 

crtn is the name of the FORTRAN subroutine to be entered when the 
specified time interval elapses. This name must be specified in 
an EXTERNAL statement in the FORTRAN routine that refer- 
ences ITIMER. The subroutine has one argument. For example: 

SUBROUTINE crtn(id) 
INTEGER id 

When the routine is entered, the value of the integer argument is 
the value specified for id in the appropriate ITIMER call 

Notes: 

1. This function can be canceled at a later time by an ICMKT function call. 

2. If the system is busy, the actual time interval after which the completion 
routine is run can be longer than the time interval requested. 

3. FORTRAN subroutines can periodically reschedule themselves by issuing 
ISCHED or ITIMER calls. 
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4. ITIMER requires a queue element, which should be considered when the 
IQSET function (Section 3.39) is executed. 

For more information on scheduling completion routines, see Section 1.2.1.2 
and the .MRKT programmed request. Section 2.43. 



Errors: 



i = Normal return. 
= 1 No queue elements available; unable to schedule request. 



Example: 



INTEGER*2 AREACil) 
EXTERNAL WATCHD 



C IF THE CODE FOLLOWING ITIMER DOES NOT REACH THE ICMKT CALL 
C IN 12 MINUTES* WATCH DOG COMPLETION ROUTINE WILL BE 
C ENTERED WITH ID OF 3 



C 



CALL ITIMER(0 .12 tO ,0 »AREA ,3 , WATCHD) 



CALL ICMKT(3!AREA) 



END 

SUBROUTINE WATCHD(ID) 
C 
C THIS IS CALLED AFTER 12 MINUTES 



RETURN 
END 



3.53 ITLOCK (FB and XM Only) 

The ITLOCK function is used in an FB or XM system to attempt to gain 
ownership of the USR. It is similar to LOCK (Section 3.73) in that, if success- 
ful, the user job returns with the USR in memory. However, if a job attempts 
to LOCK the USR while the other job is using it, the requesting job is sus- 
pended until the USR is free. With ITLOCK, if the USR is not available, 
control returns immediately and the lock failure is indicated. ITLOCK cannot 
be called from a completion or interrupt routine. 

Form: i = ITLOCK() 

For further information on gaining ownership of the USR, see the .TLOCK 
programmed request (Section 2.81). 
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Errors: 

i = Normal return. 
= 1 USR is already in use. 

Example: 

IF(ITLOCK( ) .NE.O) GOTD 100 ! GOTO 100 IF USR SUSY 



O CA ITXIMD 



The ITTINR function transfers a character from the console terminal to the 
user program. If no characters are available, system action is determined by 
the setting of bit 6 of the Job Status Word. 

Form: i = ITTINRO 

If the function result (i) is less than when execution of the ITTINR function 
is complete, it indicates that no character was available. Under the FB or XM 
monitor, ITTINR does not return a result of less than zero unless bit 6 of the 
Job Status Word was on when the request was issued. 

There are two modes of doing console terminal input, and they are governed 
by bit 12 of the Job Status Word (JSW). The JSW is at octal location 44. If bit 
12 is 0, normal I/O is performed under the following conditions: 

1. The monitor echoes all characters typed. 

2. CTRLAJ and RUBOUT perform line deletion and character dele- 
tion, respectively. 

3. A carriage return, line feed, CTRL/Z, or CTRL/C must be struck 
before characters on the current line are available to the program. 
When one of these is typed, characters on the line typed are passed 
one by one to the user program. 

If the console is in special mode (bit 12 set to 1), the following conditions 
apply: 

1. The monitor does not echo characters typed except for CTRL/C and 
CTRL/0. 

2. CTRL/U and RUBOUT do not perform special functions. 

3. Characters are immediately available to the program. 

4. No ALTMODE conversion is done. 

In special mode, the user program must echo the characters desired. However, 
CTRL/C and CTRL/0 are acted on by the monitor in the usual way. 

Bit 12 in the JSW must be set by the user program if special console mode is 
desired. Bit 14 in the JSW must be set if lower-case characters are desired. 
These bits are cleared when control returns to RT-11. 
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Regardless of the setting of bit 12, when a carriage return is entered, both 
carriage return and line feed characters are passed to the program; if bit 12 is 
0, these characters will be echoed. 

Lower-case conversion is determined by the setting of bit 14. If bit 14 is 0, 
lower-case characters are converted to upper case before being echoed (if bit 
12 is 0) and passed to a program; if bit 14 is 1, lower-case characters are 
echoed (if bit 12 is 0) and passed as received. Bit 14 is cleared when the 
program terminates. 

NOTE 

To set and/or clear bits in the JSW, do an IPEEK and then £in 
IPOKE (see example under IPOKE). In special terminal mode 
(JSW bit 12 set), normal FORTRAN formatted I/O from the 
console is undefined. 

In the FB or XM monitor, CTRL/F and CTRL/B (and CTRL/X in monitors 
with the system job feature) are not affected by the setting of bit 12. The 
monitor always acts on these characters if the SET TT FB command is in 
effect. 

Also under the FB or XM monitor, if a terminal input request is made and no 
character is available, job execution is normally suspended until a character is 
ready. If a program requires execution to continue and ITTINR to return a 
result of less than zero, it must turn on bit 6 of the JSW before the ITTINR. 
Bit 6 is cleared when a program terminates. The results of ITTINR must be 
stored in an INTEGER type variable for the purposes of error checking. Once 
it is known that the call did not have an error return, the result can be moved 
into a L0GICAL*1 variable or array element. Direct placement into a 
L0GICAL*1 variable will lead to incorrect results, because the negative flag 
(bit 15 set) is lost in conversion to a LOGICAL* 1 variable. 

Function Results: 

i >0 Character read. 
<0 No character available. 

Example: 

ICHAR=ITTINR( ) ! READ A CHARACTER FROM THE CONSOLE 

IFdCHAR.LT.O) GOTO 100 ! CHARACTER NOT AVAILABLE 



3.55 ITTOUR 



The ITTOUR function transfers a character from the user program to the 
console terminal if there is room for the character in the monitor buffer. If it is 
not currently possible to output a character, an error flag is returned. 
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Form: i = ITTOUR (char) 

where: 

char is the character to be output, right-justified in the integer (can 
be LOGICAL*! entity if desired) 

If the function result (i) is 1 when execution of the ITTOUR function is 
complete, it indicates that there is no room in the buffer and that no character 
was output. Under the FB or XM monitor, ITTOUR normally does not return 
a result of 1. Instead, the job is blocked until room is available in the output 
buffer. If a job requires execution to continue and a result of 1 to be returned, 
it must turn on bit 6 of the JSW (location 44) before issuing the request. 

NOTE 

If a foreground job has characters in the TT output buffer, they 
are not output under the following conditions: 

1. If a background job is doing output to the console TT, the 
foreground job cannot output characters from its buffer un- 
til the background job outputs a line feed character. This 
can be troublesome if the console device is a graphics termi- 
nal and the background job is doing graphic output without 
sending any line feeds. 

2. If no background job is running (that is, KMON is in con- 
trol of background), the foreground job cannot output its 
characters until the user types a carriage return or a line 
feed. In the former case, KMON gets control again and 
locks out foreground output as soon as the foreground out- 
put buffer is empty. 

Note that the use of PRINT eliminates these problems. 

Function Results: 

i = Character was output. 
== 1 Ring buffer is full. 

Example: 

DO 20 1=1 ,5 
10 IFC ITTOUR ( "007) .NE.O) GOTO 10 !RING BELL 5 TIMES 
20 CONTINUE 



3.56 ITWAIT (FB and XM Only) 

The ITWAIT function suspends the main program execution of the current 
job for a specified time interval. All completion routines continue to execute. 
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Form: i = ITWAIT (itime) 
where: 

itime is the two-word internal format time interval 

itime (1) is the high-order time 
itime (2) is the low-order time 

Notes: 

1. WAIT requires a queue element, which should be considered when the 
IQSET function (Section 3.39) is executed. 

2. If the system is busy, the actual time interval during which execution is 
suspended may be longer than the time interval specified. 

Errors: 

i = Normal return. 
= 1 No queue element available. 

Example: 

INTEGER#2 TIME(2) 

t 

t 
f 

CALL ITWAIT(TIME) IWAIT FOR TIME 



3.57 lUNTIL (FB and XM Only) 

The lUNTIL function suspends main program execution of the job until the 
time of day specified. All completion routines continue to run. 

Form: i = lUNTIL (hrs,min,sec,tick) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second on 60-cycle clocks; 
1/50 of a second on 50- cycle clocks) 

Notes: 

1. lUNTIL requires a queue element, which should be considered when the 
IQSET function (Section 3.39) is executed. 

2. If the system is busy, the actual time of day that the program resumes 
execution may be later than that requested. 
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Errors: 



i = Normal return. 
= 1 No queue element available. 



Example: 



C TAKE A LUNCH BREAK 

CALL IUNTIL(13 »0,0,0) ! START UP AGAIN AT 1 P.M. 



3.58 IVERIF 

(See SYSLIB subroutine VERIFY.) 



3.59 IWAIT 



Til-.*^ T\X7 ATT' A^T-t/n-fii-.^ a"Q^P^'^e QvpoiifirvTi r\f fVip mai'-n nrncrrpTri nntil flll 

X Etc X Vt r\J. X XUllV/L-HJll OLlb|^Cxi\-iO V/ACv/tXL-iv/iA V-*- wi*C iij.«.*ii ^^^^^i^^^^ v.-^^^- „ — 

input/output operations on the specified channel are complete. This function 
is used with IREAD, IWRITE, and ISPFN calls. Completion routines con- 
tinue to execute. 

Form: i = IWAIT (chan) 

where: 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

For further information on suspending execution of the main program, see the 
.WA.IT programm.ed request (Section 2,89). 

Errors: 

i = Normal return. 
= 1 Channel specified is not open. 

= 2 Hardware error occurred during the previous I/O operation on 
this channel. 

Example: 

IF( IWAIT(ICHAN) .NE.O) CALL lOERR(a) 



3.60 IWRITE/IWRITC/IWRITF/IWRITW 

ine luncuons ivVniiiii, ivvKiio, ivvrilix', anu ivViul v\ uransiox a apc^ixieu 
number of words from memory to the specified channel. The IWRITE func- 
tions require queue elements; this should be considered when the IQSET 
function (Section 3.39) is executed. 
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IWRITE 

The IWRITE function transfers a specified number of words from memory to 

the specified channel. Control returns to the user program immediately after 

the request is queued. No special action is taken upon completion of the 

operation. 

Form: i = IWRITE (wcnt,buff,blk,chan) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

Errors: 

i = n Normal return; n equals the number of words written, rounded 
to a multiple of 256 (0 for non-file-structured writes). 

NOTE 

If the word count returned is less than that requested, 
an implied end-of-file has occurred although the 
normal return is indicated. 

= -1 Attempt to write past end-of-file; no more space is available in 

the file. 
= -2 Hardware error occurred. 
= -3 Channel specified is not open. 

Example: 

Refer to the example for IREAD. 

IWRITC 

The IWRITC function transfers a specified number of words from memory to 
the specified channel. The request is queued and control returns to the user 
program. When the transfer is complete, the specified assembly language 
routine (crtn) is entered as an asynchronous completion routine. 

Form: i = IWRITC (wcnt,buff,blk,chan,crtn) 

where: 



y> v^xiij 



1 the r8iai.iv6 integer nuniuer ui worcis to oe Lransferrtjd 
buff is the array to be used as the output buffer 
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blk is the relative integer block number of the file to be written. The 
user program normally updates blk before it is used again (for 
example, if the program is writing two blocks at a time, blk 
should be updated by 2) 

chan is the relative integer specification for the RT-11 channel to be 
used. You must obtain this channel through an IGETC call, or 
you can use channel 16(decimal) or higher if you have done an 
ICDFN call 

crtn is the name of the assembly language routine to be activated 
upon completion of the transfer. This name must be specified in 
an EXTERNAL statement in the FORTRAN routine that 
issues the IWRITC call 



Errors: 



See the errors under IWRITE. 



Example: 



EXTERNAL CRTN 



I CODE = IWRITC C25G tIBUF »IBLK . I CHAN. CRTN) 



IWRITF 

The IWRITF function transfers a number of words from memory to the speci- 
fied channel. The transfer request is queued and control returns to the user 
program. When the operation is complete, the specified FORTRAN subpro- 
gram {crtn) is entered as an asynchronous completion routine (see Section 
1.2.1.2). 

Form: i = IWRITF (wcnt,buff,blk,chan,area,crtn) 



where: 



went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16 or higher if you have done an ICDFN call 

area is a four-word area to be set aside for link information; this area 
must not be modified by the FORTRAN program, and the USR 
must not swap over it. This area can be reclaimed by other 

crtn is the name of the FORTRAN routine to be activated upon 
completion of the transfer. This name must be specified in an 
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EXTERNAL statement in the FORTRAN routine that issues 
the IWRITF call (Section 1.2.1.2 describes completion 
routines). 

Errors: 

See the errors under I WRITE. 
Example: 

Refer to the example under IREADF, Section 3.42. 

IWRITW 

The IWRITW function transfers a specified number of words from memory to 

the specified channel. Control returns to the user program when the transfer is 

complete. 

Form: i = IWRITW (wcnt,buff,blk,chan) 

where: 

went is the integer number of words to be transferred 

buff is the array to be used as the output buffer 

blk is the integer block number of the file to be written. The user 
program normally updates blk before it is used again 

chan is the integer specification for the RT-11 channel to be used. 
You must obtain this channel through an IGETC call, or you 
can use channel 16(decimal) or higher if you have done an 
ICDFN call 

Errors: 

See the errors under IWRITE. 
Example: 

Refer to the example under IREADW, Section 3.42. 



3.61 JADD 

The JADD function computes the sum of two INTEGER*4 values. 
Form: i = JADD (joprl,jopr2,jres) 



joprl is an INTEGER*4 variable 

jopr2 is an INTEGER*4 variable 

jres is an INTEGER*4 variable that receives the sum of joprl and 
jopr2 
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Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 

Example: 

iNiEGER*a JOFi tJOPZjJRES 

IF( JADD( JOPl tJOPZ »JRES) .EQ, -Z) GOTO 100 

3.62 JAFIX 

The JAFIX function converts a REAL*4 value to INTEGER*4. 

Form: i = JAFIX (asrcjres) 

where: 

asrc is a REAL*4 variable, constant, or expression to be converted to 
INTEGER*4 

jres is an INTEGER*4 variable that is to contain the result of the 
conversion 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 

Example: 

INTEGER#a JOPl 
C READ A LARGE INTEGER FROM THE TERMINAL 

ACCEPT 9S fA 
99 FORMAT (F15,0) 

IF( JAFIK(A tJOPl) .EO.-Z) GOTO 100 



3.63 JCMP 



The JCMP function compares two INTEGER*4 values and returns an 
INTEGER*2 value that reflects the signed comparison result. 
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Form: i = JCMP (joprl,jopr2) 
where: 

joprl is the INTEGER*4 variable or array element that is the first 
operand in the comparison 

jopr2 is the INTEGER*4 variable or array element that is the second 
operand in the comparison 

Function Results: 

i = -1 If joprl is less than ;opr2. 
= li joprl is equal to jopr2. 
= 1 If joprl is greater than jopr2. 

Errors: 

None. 

Example: 

INTEGER*^ JOPK ,JOPY 



IF( JCMPf JDPX ,JOPY) ) 10 »20 .30 



3.64 JDFIX 



The JDFIX function converts a REAL*8 (DOUBLE PRECISION) value to 
INTEGER*4. 

Form: i = JDFIX (dsrcjres) 

where: 

dsrc is a REAL*8 variable, constant, or expression to be converted to 
INTEGER*4 

jres is an INTEGER*4 variable to contain the conversion result 
Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is zero. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*^ JNUM 
REAL*B DPNUM 
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20 TYPE 98 

SB FORMAK' ENTER POSITIME INTEGER') 

ACCEPT 99 ^DPNUM 
99 FORMAT (F20.0) 

IF( JDFIXCDPNUM ,JNUM) .LT.O) GOTO 20 



3.65 JDIV 

The JDIV function computes the quotient of two INTEGER*4 values. 

Form: i = JDIV (joprl,jopr2,jres[,jrem]) 

where: 

joprl is an INTEGER*4 variable that is the dividend of the operation 

jopr2 is an INTEGER*4 variable that is the divisor of joprl 

jres is an INTEGER*4 variable that receives the quotient of the 
operation (that is, jres=joprl/jopr2) 

jrem is an INTEGER*4 variable that receives the remainder of the 
operation. The sign is the same as that for joprl 

Function Results: 

i = -1 Normal return; the quotient is negative. 
= Normal return; the quotient is 0. 
= 1 Normal return; the quotient is positive. 

Errors: 

i = -3 An attempt was made to divide by 0. 

Example: 

INTEGER*-^ JN1.JN2»JC)UD 
CALL JDIM( JNl »JN2 ,JOUO) 



3.66 JICVT 

The JICVT function converts a specified INTEGER*2 value to INTEGERS. 
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Form: i = JICVT (isrcjres) 

where: 

isrc is the INTEGER* 2 quantity to be converted 

jres is the INTEGER*4 variable or array element to receive the result 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

INTEGER#4 JUAL 

CALL JICUT(il78,JUftL) ! FORM A 32-BIT CONSTANT 



3.67 JJCVT 



The JJCVT function interchanges words of an INTEGER*4 value to form an 
internal format time or vice versa. This procedure is necessary when the 
INTEGER*4 variable is to be used as an argument in a timer-support func- 
tion such as ITWAIT. When a two-word internal format time is specified to a 
function such as ITWAIT, it must have the high-order time as the first word 
and the low-order time as the second word. 

Form: CALL JJCVT (jsrc) 

where: 

jsrc is the INTEGER*4 variable whose contents are to be inter- 
changed 

Errors: 

None. 

Example: 

INTEGER*^ TIME 



CALL GTIM(TIME) ! GET TIME OF DAY 

CALL JJCUT(TIME) ! TURN IT INTO INTEGER*a FORMAT 



3.68 JMOV 



The JMOV function assigns the value of an INTEGER*4 variable to another 
INTEGER*4 variable and returns the sign of the value moved. 
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Form; i = JMOV (jsrcjdest) 

where: 

jsrc is the INTEGER*4 variable whose contents are to be moved 
jdest is the INTEGER*4 variable that is the target of the assignment 

Function Results: 

The value of the function is an INTEGER*2 value that represents the sign of 
the result as follows: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

None. 

Example: 

The JMOV function allows an INTEGER*4 quantity to be compared 
with by using it in a logical IF statement. For example: 

INTEGER*^:! INTl 

* 

IF( JMOy ( INTl f INTl ) ,NE .0 ) GOTO 300 ! GO TO STMT 300 IF INTl NOT 

3.69 JMUL 

The JMUL function computes the product of two INTEGER*4 values. 

Form: i = JMUL (joprl,jopr2,jres) 

where: 

joprl is an INTEGER*4 variable that is the multipUcand 

jopr2 is an INTEGER*4 variable that is the multiplier 

jres is an INTEGER*4 variable that receives the product of the 
operation 

Function Results: 

i = -1 Normal return; the product is negative. 
= Normal return; the product is 0. 
= 1 Normal return; the product is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
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Example: 

INTEGER#a Jl ,J2 .JRES 



IF( JMUL( Jl .J2,JRES)+1 ) 100,10 ,20 
C GOTO lOO IF OMERFLOW . 
C GOTO 10 IF RESULT IS NEGATIOE 
C GOTO 20 IF RESULT IS POSITIME OR ZERO 



3.70 JSUB 



The JSUB function computes the difference between two INTEGER*4 
values. 

Form: i = JSUB (joprl,jopr2,jres) 

where: 

joprl is an INTEGER*4 variable that is the minuend of the operation 

jopr2 is an INTEGER*4 variable that is the subtrahend of the 
operation 

jres is an INTEGER*4 variable that is to receive the difference 
between ioprl and iopr2 (that is, jres=joprl-jopr2) 

Function Results: 

i = -1 Normal return; the result is negative. 
= Normal return; the result is 0. 
= 1 Normal return; the result is positive. 

Errors: 

i = -2 An overflow occurred while computing the result. 
Example: 

INTEGER*/!! J0P1,J0P2,J3 

t 
t 
* 

CALL JSUB( JOPl ,J0P2 ,J3) 



3.71 JTIME 



The JTIME subroutine converts the time specified to the internal two-word 
format time. 
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Form: CALL JTIME (hrs,min,sec,tick,time) 

where: 

hrs is the integer number of hours 

min is the integer number of minutes 

sec is the integer number of seconds 

tick is the integer number of ticks (1/60 of a second for 60-cycle 
clocks; 1/50 of a second for 50-cycle clocks) 

time is the two-word area to receive the internal format time: 
time(l) is the high-order time; time(2) is the low-order time 

Errors: 

None. 

Example: 

INTEGER*^ Jl 



C CONUERT 3 HRB » 7 MIN, 23 SECONDS TO INTEGER #4 UALUE 
CALL JTIMEO ,7 ,23 ,0 ,J1 ) 
CALL JJCvT ( Jl ) 



3.72 LEN 



The LEN function returns the number of characters currently in the string 
contained in a specified array. This number is computed as the number of 
characters preceeding the first null byte encountered. If the specified array 
contains a null string, a value of is returned. 

Form: i = LEN (a) 

where: 

a specifies the array containing the string, which must be terminated 
by a null byte 

Errors: 

None. 

Example: 

LOGICAL*! STRNG(73) 



TYPE 99 , (STRNG( I) ,1 = 1 ,LEN(STRNG) ) 
99 FORMAT( '0' ,132A1 ) 
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3.73 LOCK 



The LOCK subroutine keeps the USR in memory for a series of operations 
involving various RT-11 file management functions. 

If all the conditions that cause swapping are satisfied, a portion of the user 
program is written out to the disk file SWAP.SYS and the USR is loaded. 
Otherwise, the USR in memory is used, and no swapping occurs. The USR is 
not released until an UNLOCK (see Section 3.109) is given. (Note that in an 
FB system, calling the CSI can also perform an imphcit UNLOCK.) To save 
time in swapping, a program that has many USR requests to make can LOCK 
the USR in memory, make all the requests, and then UNLOCK the USR. 

In an FB or XM environment, a LOCK inhibits another job from using the 
USR. Thus, the USR should be locked only for as long as necessary. 

NOTE 

If any job does a LOCK, it can cause the USR to be unavailable 
for other jobs for a considerable period of time. The USR is not 
reentrant and only one job has use of the USR at a time, which 
should be considered for systems requiring concurrent fore- 
ground and background jobs. This is particularly true when 
magtape and/or cassette are active. 

File operations by the USR require a sequential search of the 
tape for magtape and cassette. This could lock out the fore- 
ground job for a long time while the background job does a tape 
operation. The programmer should keep this in mind when 
designing such systems. The FB and XM monitors supply the 
ITLOCK routine, which permits the foreground job to check for 
the availability of the USR. 

Form: CALL LOCK 

After a LOCK has been executed, the UNLOCK routine must be executed to 
release the USR from memory. The LOCKAJNLOCK routines are comple- 
mentary and must be matched. That is, if three LOCKs are issued at least 
three UNLOCKs must be done, otherwise the USR is not released. More 
UNLOCKS than LOCKs can occur without error; the extra UNLOCKs are 
ignored. 

Notes: 

1. It is vital that the LOCK call not come from within the area into which 
the USR will be swapped. If this should occur, the return from the USR 
request would not be to the user program, but to the USR itself, since the 
LOCK function causes part of the user program to be saved on disk and 
replaced in memory by the USR. Furthermore, subroutines, variables, and 
arrays in the area where the USR is swapping should not be referenced 
while the USR is locked in memory. 
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2. Once a LOCK has been performed, it is not advisable for the program to 
destroy the area the USR is in, even though no further use of the USR is 
required. This causes unpredictable results when an UNLOCK is done. 

3. LOCK cannot be called from a completion or interrupt routine. 

4. If a SET USR NOSWAP command has been issued, LOCK and UN- 
LOCK do not cause the USR to swap. However, in FB, LOCK still inhi- 
bits the other job from using the USR, and UNLOCK allows the other job 
access to the USR. 

5. The USR cannot accept argument lists, such as device file name specifica- 
tions, located in the area into which it has been locked. 

Errors: 

None. 
Example: 

INTEGER#2 D5LK(4) 

DATA DBLK /3RDK ,3RDT »3RF I L »3RFa / 



CALL LOCK !LOCK THE USR IN MEMORY 

ICHN=GETC() !GET A CHANNEL TO USE 

IF(LOOKUP(ICHN,DBLK) ,LT.O) STOP '7L00KUP FAILED' 
CALL UNLOCK 'RELEASE THE USR 



3.74 LOOKUP 



The LOOKUP function associates a specified channel with a device and/or 
file for the purpose of performing I/O operations. The channel used is then 
busy until one of the following functions is executed. 

CLOSEC or ICLOSE 

ISAVES 

PURGE 

Form: i = LOOKUP (chan,dblk[, count, seqnum,]) 
i = LOOKUP (chan,jobdes) 



where: 



is the integer specification for the RT-11 channel to be asso- 
ciated with the file. You must obtain this channel through an 
IGETC call, or you can use channel 16 or higher if you have 
done an ICDFN call 
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dblk is the four-word area specifying the Radix-50 file descriptor. 

Note that unpredictable results occur if the USR swaps over 
this four- word area 

count is an optional argument used for the cassette handler; this 
argument defaults to 

seqnum is a file number. For cassette operations, if this argument is 
blank, a value of is assumed. 

For magtape, it describes a file sequence number. The action 
taken depends on whether the file name is given or null. The 
sequence number can have the following values: 

-1 Suppress rewind and search for the specified file name 
from the current tape position. If a file name is given, a 
file-structured lookup is performed (do not rewind). If 
the file name is null, a non-file-structured lookup is 
done (tape is not moved). You must specify a -1 and no 
other negative number. 

Rewind to the beginning of the tape and do a non-file- 
structured lookup. 

n Where n is any positive number. Position the tape at 
file sequence number n and check that the file names 
match. If the file names do not match, an error is gener- 
ated. If the file name is null, a file-structured lookup is 
done on the file designated by seqnum. 

jobdes is an argument that allows communication between jobs in a 
system job environment. It is a pointer to a four-word job 
descriptor of the job to which messages will be sent or 
received. 

jobdes - .RAD50 /MQ/ 

.ASCII /logical-job-name/ 

where the logical-job-name is six characters long. If the 
logical-job-name is zero, the channel will be opened only 
for .READ/C/W requests, and such requests will accept 
messages from any jobs. 

NOTE 

The arguments of LOOKUP must be positioned so that the 
USR does not swap over them. 

The handler for the selected device must be in memory for a LOOKUP. If the 
first word of the file name in dblk is and the device is a file-structured 
device, absolute block of the device is designated as the beginning of the file. 
This technique, called a non-file-structured lookup, allows I/O to any ph3'sical 
block on the device. If a file name is specified for a device that is not file 
structured (such as LP:FILE.TYP), the name is ignored. 



3-74 System Subroutine Description and Examples 



NOTE 

Since a non-file-structured lookup allows I/O to any physical 
block on the device, the user must be aware that, in this mode, 
it is possible to overwrite the RT-11 device directory, thus de- 
stroying all file information on the device. 

Function Results: 

i = n Normal return; n equals the number of blocks in the file (0 for 






Errors: 



i = -1 Channel specified is already open. 

= -2 File specified was not found on the device. 

= -3 Device in use. 

= -4 Tape drive is not available. 



Example: 



INTEGER*2 DBLK(a) 

DATA DBLK/3RDK0 »3RFTN »3R44 f3RDAT/ 



ICHAN=IGETC( ) 

IF( ICHAN.LT.O) STOP 'NO CHANNEL' 
IFaFETCH(DBLK) .NE.O) STOP 'BAD FETCH' 
IF(L0DKUP(ICHAN*D8LK) ,LT.O) STOP 'BAD LOOKUP' 



CALL ICLDSEdCHAN .1) 

I = ICLOSEC) 

CALL IFREEC(ICHAN) 



or using LOOKUP with a system job 



LOGICAL*! JNAM(G) 
DIMENSION JBLK(4) 
EQUIUALENCE ( JNAM C 1 ) » JBLK ( 2 ) ) 
DATA JNAM / ' Q ' , 'W , '£' , 'W > ' E' >0 / 
DATA JBLKCl ) /3RM0 / 



OPEN A MESSAGE CHANNEL TO 'QUEUE' 

ICHN = GETC( ) 

IFCLOOKUP( ICHN tJBLK) .LT.O) STOP 'QUEUE IS NOT RUNNING' 
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3.75 MRKT 



The MRKT function schedules an assembly language completion routine to 
be entered after a specified time interval has elapsed. Support for MRKT in 
SJ requires timer support. 

Form: i = MRKT (id,crtn,time) 

where: 

id is an integer identification number to be passed to the routine 
being scheduled 

crtn is the name of the assembly language routine to be entered when 
the time interval elapses. This name must be specified in an 
EXTERNAL statement in the FORTRAN routine that issues 
the MRKT call 

time is the two- word, internal format time interval; when this interval 
elapses, the routine is entered. If considered as a two-element 
INTEGER*2 array: 

time (1) is the high-order time, 
time (2) is the low-order time. 

Notes: 

1. MRKT requires a queue element, which should be considered when the 
IQSET function (Section 3.39) is executed. 

2. If the system is busy, the time interval that elapses before the completion 
routine is run can be greater than that requested. 

For further information on scheduling completion routines, see the .MRKT 
programmed request (Section 2.43). 



Errors: 



i = Normal return. 
= 1 No queue element was available; unable to schedule request. 



i-JAClliiplC. 



INTEGER#2 TINT(2) 
EXTERNAL ARTN 



CALL MRKT(a»ARTN .TINT! 



3.76 MTATCH (Special Feature) 

The MTATCH subroutine attaches a terminal for exclusive use by the re- 
questing job. This operation must be performed before any job can use a 
terminal with multi-terminal programmed requests. 
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Form: i = MTATCH (unit[,addr,],[jobnum]) 

where: 

is the logical unit number {lun) of the terminal 



unit 
addr 



is the optional address of an asynchronous terminal status 
word. Omit this argument if the asynchronous terminal 
status word is not required by specifying a comma. For 
example: 

I = MTATCH (unit„jobnum) 

jobnum is the job number associated with the terminal if the termi- 
nal is not available 



Errors: 



i = Normal return. 
= 3 Nonexistent unit number. 

= 5 Unit attached by another job (job number returned in jobnum) 
= 6 In XM monitor, the optional status word address is not in a 
valid user virtual address space 



Example: 



TEST SYSLIB MULT I -TERM INAL ROUTINES 

INTEGER*2 UN I T ,SBLOK ( 4 ) , STAT (8) jASW fSTRINGCai ) tPRaMPT(8J 

LOGICAL+1 TEND! 11) 

REAL»a TESTMO) 

DATA PROMT/ 'EN' . 'TE' . 'R ' » 'BT' t'RI ' . 'NG' . ' > ' ,"200/ 

DATA TEND/ '*' I 'E ' . 'N ' , 'D' t ' ' , 'T ' , 'E ' , 'S ' . ' T ' . ' * ' ,0/ 

DATA TESTM/ 'STAT' . 'ATCH' ; 'GET' . 'SET' ,'',''.''. 

USE MTSTAT TO GET & DISPLAY NO. OF UNITS 



'DTCH' 



TYPE lOB 

L=l 

IF(MTSTAT(STAT) .NE.O)GOTO 999 

TYPE 99.STAT(3) 

GET UNIT » TO TEST 



ANNOUNCE TEST 
L = FUNC CODE 
GET MTTY STATUS 
! DISPLAY s UNITS 



! TYPE PROMPT 
! GET UNIT » 



TYPE 100 

ftCCEPT 101 .UNIT 

IF(UNIT,E(3.99) STOP 'END DF MULT I -TERMI NAL TEST ' i UNIT s99 STOPS TEST 

ATTACH UNIT TO THIS JOB THEN GET TCB STATUS WORDS 



TYPE 110 

ACCEPT 111 tIASW 

IFdASW.EO. 'Y' ) IER = MTATCH(UNIT (ASW ,JOB) 

IF( lASW.NE, 'Y' ) IER = MTftTCH(UNIT .0 .JOB) 

L = 2 

IF(IER)GOTO 999 

L = 3 

IF(MTGET(UNIT .SBLOKC 1 ) ) .NE.O)G0T0 999 

TYPE 102 .UNIT ,SBLOK 

GET NEW STATUS. PUT IT IN TCB, THEN DISPLAY IT 

CALL SETUP(SBL0K .UNIT) 

L = a 



SEE IF ASW TEST 
IS TO BE DONE 
ATT W/ ASW IF YES 
ATT W/0 ASW IF NO 

! REPORT ERROR IF ANY 

! GET TCB WORDS 

! DISPLAY CONTENTS 



! GET CHANGES IF ANY 
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IF(MTSET(UNIT ,BBLOK( 1) ) ,NE.O)GOTD 999 
TYPE 102 , UNIT ,SBLOK 



! GET NEW TCB STATUS 
! THEN DISPLAY IT. . . 



PERFORM TEST - FIRST ECHO INPUT THEN REPEAT IT USING MTIN & MTOUT 



30 



TYPE 

TYPE 

TYPE 

CALL 

CALL 

IF(J, 

CALL 



103 

104 

105 

MTIN(UNIT ,J) 

MTOUT(UNIT (J) 

NE, 10) GOTO 30 

MTRCTO(UNIT) 



! ANNOUNCE RULES OF 

! THE TEST. . , 

! GET LINE OF INPUT 

! REPEAT IST/ECHO 2ND 

! LF = END OF LINE 

! RESET CTRL/0 



40 



NOW TEST W/ TTSPC$ BIT ON 
THEN TURN TTSPC$ BIT OFF.. 



ECHO INPUT WITH MTOUT (DON'T REPEAT) 



IF(SBLDK( 1 ) .AND. " 10000) GOTO 40 
SBLOK( 1 )=SBLOK( 1 ) .OR, "10000 
IF(MTSET(UNIT .SBLOK( 1 ) ) .NE.O)GOTD 999 
GOTO 30 

SBLOK( 1 )=SBLOK( 1 ) .AND, .NOT, "10000 
IF(MTSET(UNIT ,SBLQK( 1 ) ) ,NE,0)GOTO 999 
IFdASW.NE. 'Y' )GDTQ 60 



IF TTSPC$ ON BRANCH 

SET TTSPC$ BIT 

UPDATE TCB 

GO DO 2ND TEST 

TURN OFF TTSPC$ BIT 

UPDATE TCB 

SKIP ASW TEST? 



C ASYNCHRONOUS STATUS WORD TEST - "POLL" TERMINAL UNTIL INPUT 
C AVAILABLE - ECHO INPUT THEN REPEAT IT ON NEXT LINE 



TYPE 109 
50 IF(ASW, AND. .NOT, "40000) GOTO 50 
55 CALL MTIN(UNIT ,J) 

CALL MTOUT(UNIT ,J) 

IF( J.NE. 10)G0T0 55 

CALL MTRCTO(UNIT) 



ANNOUNCE TEST 
WAIT FOR INPUT 
GET CHAR 
OUTPUT CHAR 
END ON LINE FEED 
RESET CTRL/0 



C 
GO 



TEST MTPRNT BY OUTPUTTING 2 STRINGS. 1 FROM USER & 1 INTERNAL 



CALL GTLINCSTRING, PROMT) 
CALL MTPRNTCUNIT (STRING) 
CALL MTPRNT(UNIT >TEND) 



GET STRING MIA GTLIN 
OUTPUT TO TERMINAL 
ANNOUNCE END OF TEST 



DETACH UNIT FROM JOB AND START OUER 



L = 9 

TYPE 108 (UNIT 

IF(MTDTCH(UNIT) .EO,0)GOTO 



! DETATCH UNIT 

! FROM JOB THEN LOOP 



C 
999 



99 

100 

101 

102 

103 

104 

105 

lOB 

108 

109 

110 

111 

909 



ERROR REPORTING 

TYPE S09,TESTM(L) 
GOTO 5 



lER 



! ANNOUNCE ERROR 
! THEN START O'.'ER 



FORMAT( 'GTHERE ARE', 13.' UNITS ON THIS SYSTEM') 

FORMAT( '$UNIT » TO BE TESTED?') 

FORMAT (12) 

FORMAT ( 'OUNIT' .13, ' STATUS =',408) 

FORMAT('OGO TO TERMINAL BEING TESTED ... ENTER 2 LINES + <RET>') 

FORMAT(' 1ST LINE: INPUT WILL BE ECHOED THEN REPEATED') 

FORMAT(' 2ND LINE: TEST TTSPC$ ON - INPUT ECHOED OIA MTOUT'/) 

FORMAT('l SYSLIB MUL I -TERMINAL ROUTINE TEST PROGRAM') 

FORMAT(' ABOUT TO DETATCH UNIT « '.12) 

FORMAT(' TEST ASW - INPUT WILL BE ECHOED, THEN REPEATED'/) 

FORMATC '$TEST ASYNCH STATUS WORD FUNCTION''') 

FORMATfAl ) 

FORMAT( 'OMT' .A4 , ' ERROR CODE =',I3) 

END 
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SUBROUTINE TO GET NEW STATUS WORD UALUES 
SUBROUTINE SETUP ( SBLOK »UNI T ) 
INTEGER SBL0K(4) »UNIT 





TYPE 100 




ACCEPT 101 ,J 




IFf J)SBLOK( n=J 




TYPE 102 




ACCEPT 101 ,J 




TYPE 103 




ACCEPT 101 .1 




IF(I,QR.J)SBL0K(3)=I»25G+J 


5 


TYPE 104 




ACCEPT 105.1 




IF( I )SBLQK(a)=SBL0KC4)/25G*25B+I 




RETURN 


100 


FORMAT( '$CONFIG BIT MASK:') 


101 


FORMAT (OG) 


102 


FORMAT{ '$CHAR REQUIRING FILLER:') 


103 


FORMAT('$s OF FILL CHARS:') 


loa 


FORMAT! '$CARRIAGE WIDTH:') 


105 


FORMAT! 13) 




END 



PROMPT FOR NEW CONFIG WORD 

ACCEPT INPUT 

UPDATE IF ANY INPUT 

ASK FDR FILL CHAR 

ACCEPT IT 

ASK FOR » OF FILL CHARS 

ACCEPT IT TOD 

p U T T M D tj n D IT O R y T C C 

ASK FOR CARRIAGE WIDTH 
ACCEPT IT 

SET BUT DON'T MESS WITH 
STATE WORD . . . RETURN 



3.77 MTDTCH (Special Feature) 

The MTDTCH subroutine is the complement of the MTATCH subroutine. Its 
function is to detach a terminal from a particular job and make it available 
for other jobs. 

Form: i = MTDTCH(unit) 

where: 

unit is the logical unit number (lun) of the terminal to be detached 

Errors: 

i = Normal return. 
= 2 Invalid unit number; terminal is not attached. 
= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.78 MTGET (Special Feature) 

The MTGET subroutine furnishes the user with information about a specific 
terminal in a multi-terminal system. 

Form: i = MTGET (unit,addr[,jobnum]) 

where: 

unit is the unit number of the line and terminal whose status is 

desired 
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addr is the four-word area to receive the status information. The 

area is a four-element INTEGER*2 array (see the .MTSET 
programmed request, Section 2.51, for area format). 

jobnum is the job number associated with the terminal if the terminal 
is not available 

Status information including bit definitions for the terminal configuration 
words and the terminal state byte are described in detail under the .MTGET 
programmed request. 

Errors: 

i = Normal return. 

= 2 Unit not attached. 

= 3 Nonexistent unit number. 

= 4 Unit attached by another job (job number returned in jobnum). 

= 6 In XM monitor, the address of the terminal buffer is outside the 
valid program limits. 

Example: 

Refer to the example under MTATCH. 



3.79 MTIN (Special Feature) 



The MTIN subroutine transfers characters from a specified terminal to the 
user program. This subroutine is a multi-terminal form of ITTINR. If no 
characters are available, an error flag is set to indicate an error upon return 
from the subroutine. If no character count argument is specified, one charac- 
ter is transferred. 

Form: i = MTIN (unit,char[,chrcnt ][,ocnt]) 

where: 

unit is the unit number of the terminal 

char is the variable to contain the characters read in from the ter- 
minal indicated by the unit number 

chrcnt is an optional argument that indicates the number of charac- 
ters to be read 

ocnt is an optional argument that indicates the number of charac- 
ters actually transferred 

When a request for a multiple -character transfer is requested, if the optional 
fourth argument {ocnt) is specified and bit 6 of the M.TSTS word is set, the 
variable specified as the argument will have a value equal to the actual 
number of characters transferred upon return from the subroutine. 

Errors: 

i = Normal return. 
= 1 No input available. 
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= 2 Unit not attached. 

= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.80 MTOUT (Special Feature) 

ine iViiiJUi suorouime transiers cnaracLers lu a speuuieu Leimmai. nns 
subroutine is a multi-terminal form of ITTOUR. If no room is available in the 
output ring buffer, an error flag is set to indicate an error upon return from 
the subroutine. If no character count argument is specified, one character is 
transferred. 

Form: i = MTOUT (unit,char[,chrcnt][,ocnt]) 

where: 

unit is the unit number of the terminal 

char is the variable or array containing the characters to be output, 
right-justified in the integer (can be LOGICAL*! if desired) 

chrcnt is an optional argument that indicates the number of charac- 
ters to be output 

ocnt is an optional argument that indicates the number of charac- 
ters actually transferred 

When a request for a multiple- character transfer is requested, if the optional 
fourth argument (ocnt) is specified and bit 6 of the M.TSTS word is set, the 
variable specified as the argument will have a value equal to the actual 
number of characters transferred upon return from the subroutine. 

Errors: 

i = Normal return. 
= 1 No room in output ring buffer. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

= 5 In the XM monitor, the address of the user buffer is outside the 
valid program limits. 

Example: 

Refer to the example under MTATCH. 



3.81 MTPRNT (Special Feature) 

The MTPRNT subroutine allows output to be printed at any terminal in a 
multi-terminal environment. This subroutine has the same effect as the 
PRINT subroutine (Section 3.86). 
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Form: i = MTPRNT (unit,string) 

where: 

unit is the unit number associated with the terminal 

string is the character string to be printed. Note that all quoted liter- 
als used in FORTRAN subroutine calls are in ASCIZ format, 
which ends in zero for a CR/LF or a 200 if no action is to be 
taken 



Errors: 



Normal return. 

2 Unit not attached. 

3 Nonexistent unit number. 

5 In the XM monitor, the address of the character string is out- 
side the valid program limits. 



3.82 MTRCTO (Special Feature) 

The MTRCTO subroutine resets the CTRL/0 command typed at the speci- 
fied terminal in a multi-terminal environment. This subroutine has the same 
effect as the .RCTRLO programmed request (Section 2.59). 

Form: i = MTRCTO{unit) 

where: 

unit is the unit number associated with the terminal 

Errors: 

i = Normal return. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

Example: 

Refer to the example under MTATCH. 



3.83 MTSET (Special Feature) 

The MTSET subroutine sets terminal and line characteristics. The set condi- 
tions remain in effect until the system is booted or the terminal and line 
characteristics are reset. See the .MTSET programmed request (Section 2.51) 
for more details. 

Form: i = MTSET (unit,addr) 

where: 

unit is the unit number of the line and terminal whose characteristics 
are to be changed 
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addr is a four- word area to pass the status information. The area is a 
four-element INTEGER*2 array 



Errors: 

i = Normal return. 
= 2 Unit not attached. 
= 3 Nonexistent unit number. 

==6 In the XM monitor, the address of the status block is outside 
the valid program limits. 

Example: 

Refer to the example under MTATCH. 



3.84 MTSTAT (Special Feature) 

The MTSTAT subroutine returns multi-terminal system status in an eight- 
word status block. 



Form: i = MTSTAT (addr) 



where: 



addr is the address of an ^ight-word array where multi-terminal 
status information is returned. The status block contains the 
following information: 



addr(l) 






addr(3) 

addr(4) 
addr(5)-(8) 



Contents 

Offset from the base of the resident monitor to 
the first Terminal Control Block (TCB). 

r^^^Go-f ^^r\tnrk fV»p V>PQQ r\^ i^Vip rooirlanf rnnnifnr to 

the terminal control block of the console terminal 
for the program. 

The number of terminal control blocks built into 
the system (1-17 decimal). 

The size of the terminal control block in bytes. 
Reserved. 



Errors: 



i = Normal return. 
= 5 In the XM monitor, the address of the status block is not in 
valid user address space. 

Example: 

Refer to the example under MTATCH. 
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3.85 MWAIT (FB and XM Only) 

The MWAIT subroutine suspends main program execution of the current job 
until all messages sent to or from the other job have been transmitted or 
received. It provides a means for ensuring that a required message has been 
processed. MWAIT is used primarily in conjunction with the IRCVD and 
ISDAT calls, where no action is taken when a message transmission is com- 
pleted. This subroutine requires a queue element, which should be considered 
when the IQSET function (Section 3.39) is executed. 

Form: CALL MWAIT 

Errors: 

None. 
Example: 

Refer to the example under ISDAT, Section 3.48. 



3.86 PRINT 

The PRINT subroutine prints output from a specified string at the console 
terminal. This routine can be used to print messages from completion routines 
without using the FORTRAN formatted I/O system. Control returns to the 
user program after all characters have been placed in the output buffer. 

The string to be printed can be terminated with either a null (0) byte or a 200 
• (octal) byte. If the null (ASCIZ) format is used, the output is automatically 
followed by a carriage return/line feed pair (octal 15 and 12). If a 200 byte 
terminates the string, no carriage return/line feed pair is generated. 

In the FB monitor, a change in the job that is controlling terminal output is 
indicated by a B> or F>. Any text following the message has been printed by 
the job indicated (foreground or background) until another B> or F> is 
printed. When PRINT is used by the foreground job, the message appears 
immediately, regardless of the state of the background job. Thus, for urgent 
messages, PRINT should be used rather than ITTOUR" 

Form: CALL PRINT (string) 
where: 

string is the string to be printed. Note that all quoted literals used in 
FORTRAN subroutine calls are in ASCIZ form.at, as are all 
strings produced by the SYSLIB string-handling package (The 
CONCAT routine can be used to append an octal 200 to an 
ASCIZ string; see example.) 

Errors: 

None. 
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Example: 

CALL PRINT ('THE COFFEE IS READY') 



BYTE QUESTION (80; 

! APPEND BYTE 200 

CALL CONCAT('WHAT IS YOUR NAME? ' t200 .QUEST ION ) 

CALL PRINT(QUEBTION) lOUESTION PRINTS WITHOUT CR.LF 



3.87 PURGE 



The PURGE subroutine deactivates a channel without performing an 
ISAVES, CLOSEC, or ICLOSE. Any tentative file currently associated with 
the channel is not made permanent. This subroutine prevents entered 
(lENTER or .ENTER) files from becoming permanent directory entries. 

Form: CALL PURGE (chan) 

where: 

chan is the integer specification for the RT-11 channel to be deac- 
tivated 

Errors: 

None. 
Example: 

Refer to the example under lENTER, Section 3.24. 



3.88 PUTSTR 



The PUTSTR subroutine writes a variable-length character string to a speci- 
fied FORTRAN logical unit. PUTSTR can be used in main program routines 
or in completion routines but not in both in the same program at the same 
time. If PUTSTR is used in a completion routine, it must not be the first I/O 
operation on the specified logical unit. 

Form: CALL PUTSTR (lun, in, char, err) 
where: 

lun is the integer specification of the FORTRAN logical unit num- 
ber to which the string is to be written 

in is the array containing the string to be written 

char is an ASCII character that is appended to the beginning of the 
string before it is output. If 0, no extra character is output. This 
character is used primarily for carriage control purposes 
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err is a LOGICAL*! variable that is .TRUE, for an error condition 
and .FALSE, for a no-error condition 

Errors: 

err = -1 End-of-file for write operation. 

-2 Hardware error for write operation. 

Example: 

LOGICAL*! STRNGCBl ) ,ERR 



mUTPUT STRING WITH DOUBLE SPACING 
CALL PUTSTR(7 fSTRNG , '0' ,ERR) 



3.89 R50ASC 



THE R50ASC subroutine converts a specified number of Radix-50 characters 
to ASCIL 

Form: CALL R50ASC {icnt,input,output) 

where: 

icnt is the integer number of ASCII characters to be produced 

input is the area from which words of Radix-50 values to be 
converted are taken. Note that {icnt+2)/d words are read for 
conversion 

output is the area into which the ASCII characters are stored 
Errors: 

If an input word contains illegal Radix-50 codes — that is, if the input 
word is greater (unsigned) than 174777(octal) — the routine outputs 
question marks for the value. 

Example: 

REAL*8 NAME 
LOGICAL*! OUTPdZ) 



CALL R50ASC(12 (NAME.OUTP) 



3.90 RAD50 



The RAD50 function provides a method of encoding RT-11 file descriptors in 
Radix-50 notation. The RAD50 function converts six ASCII characters from 
the specified area, returning a REAL*4 result that is the two-word Radix-50 
value. 
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Form: a = RAD50 (input) 

where: 

input is the area from which the ASCII input characters are taken 

The RAD50 call: 

A = RAD50 (LINE) 

is exactly equivalent to the IRAD50 call: 

CALL IRAD50 (B.LINEtA) 

Function Results: 

The two-word Radix-50 value is returned as the function result. 



3.91 RCHAIN 



The RCHAIN subroutine allows a program to determine whether it has been 
chained to and to access variables passed across a chain. If RCHAIN is used, 
it must be used in the first executable FORTRAN statement in a program. 

Form: CALL RCHAIN (flag,var,wcnt) 



where: 



flag is an integer variable that RCHAIN will set to -1 if the program 
has been chained to; otherwise, it is 

var is the first variable in a sequence of variables with increasing 
memory -addresses to receive the information passed across the 
chain (see Section 3.2) 

went is the number of words to be moved from the chain parameter 
area to the area specified by var. RCHAIN moves went words 
into the area beginning at var 



Errors: 

None. 

Example: 



INTEGER*Z PARMB(50) 

CALL RCHAIN( IFLAG ^PARMS .50) 

IF(IFLAG) GOTO 10 ! GOTO 10 IF CHAINED TO 



3.92 RCTRLO 



The RCTRLO subroutine resets the effect of any console terminal CTRL/0 
command that was typed. After an RCTRLO call, any output directed to the 
console terminal prints until another CTRL/0 is typed. 
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Form: CALL RCTRLO 
Errors: 

None. 
Example: 

CALL RCTRLO 

CALL PRINT ('PRINT UNTIL ANOTHER CTRL/0 TYPED' 



3.93 REPEAT 



The REPEAT subroutine concatenates a specified string with itself to pro- 
duce the indicated number of copies. REPEAT places the resulting string in a 
specified array. 

Form: CALL REPEAT (in,out,i[,len[,err]]) 
where: 

in is the array containing the string to be repeated; it must be termi- 
nated with a null byte 

out is the array into which the resultant string is placed. This array 
must be at least one element longer than the value of len, if len is 
specified. It also must be terminated with a null byte if len is 
specified 

i is the integer number of times to repeat the string 

len is the integer number representing the maximum length of the 
output string 

err is the logical error flag set if the output string is truncated to the 
length specified by len 

Input and output strings can specify the same array only if the repeat count 
(0 is 1 or 0. When the repeat count is 1, this routine is the equivalent of 
~>wv^x X, ..xiCxx i,ii^ ifc^cai. wuuiii. IB \j, uuv IS repiacea oy a nun strmg. ine old 
contents of out are lost when this routine is called. 

Errors: 

Error conditions are indicated by err, if specified. If err is given and the 
output string would have been longer than len characters, then err is set 
to .TRUE.; otherwise, err is unchanged. 

Example: 

LOGICAL*! SI|\1(21) ,SOUT( 101 ) 

t 

CALL REPEATCSIN fSOUT t5) 
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3.94 RESUME (FB and XM Only) 

The RESUME subroutine allows a job to resume execution of the main pro- 
gram. A RESUME call is normally issued from an asynchronous FORTRAN 
routine entered on I/O completion or because of a schedule request (see the 
SUSPND subroutine, Section 3.102, for more information). 

Form: CALL RESUME 
Errors: 

None. 
Example: 

Refer to the example under SUSPND. 



3.95 SCCA 

The SCCA subroutine provides a CTRL/C intercept to: 

1. Inhibit a CTRL/C abort 

2. Indicate that a CTRL/C command is active 

3. Distinguish between single and double CTRL/C comm-ands 

Form: CALL SCCA [(iflag)] 

where: 

iflag is an integer terminal status word that must be tested and 
cleared to determine if two CTRL/Cs were typed at the console 
terminal; the iflag must be an INTEGER*2 variable (not 
LOGICAL*!) 

When a CTRL/C is typed, the SCCA subroutine places it in the input ring 
buffer. While residing in the buffer, the character can be read by the program. 
The program must test and clear the iflag to determine if two CTRL/C com- 
mands were typed consecutively. The iflag is set to non-zero when two 
CTRL/Cs are typed together. It is the responsibility of the program to abort 
itself if appropriate, on an input of CTRL/C from the terminal. The SCCA 
subroutine with no argument disables the CTRL/C intercept. A CTRL/C from 
indirect command files is not intercepted by SCCA. 

Errors: 

None. 

Example: 

PROGRAM SCCA 
C SCCA. FOR SYSLIB TEST FOR SCCA 

C 
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CALL PRINT ('PROGRAM HAS STARTED t TYPE') 

IFLAG=0 

CALL SCCA (IFLAG) 
10 I = ITTINR() !GET A CHARACTER 

IF (I .NE. 3) GOTO 10 
C A CTRL/C WAS TYPED 

CALL PRINT ('A CTRL/C WAS TYPED') 

IF (IFLAG .EO, 0) GOTO 10 

CALL PRI-NT ('A DOUBLE CTRL/C WAS TYPED') 

TYPE 13, IFLAG 
13 FORMAT ( ' IFLAG = ' ,0G,/) 

CALL SCCA IDISABLE CTRL/C INTERCEPT 

CALL PRINT ('TYPE A CTRL/C TO EXIT') 
20 GOTO 20 !L00P UNTIL CTRL/C TYPED 

END 



3.96 SCOMP/ISCOMP 

The SCOMP routine compares two character strings and returns the integer 
result of the comparison. 

Form: CALL SCOMP (a,b,i) 
or 
i = ISCOMP (a,b) 

where: 

a is the array containing the first string; it must be terminated with a 
null byte 

b is the array containing the second string; it must be terminated 
with a null byte 

i is the integer variable that receives the result of the comparison 

The strings are compared from left to right, one character at a time, using the 
collating sequence specified by the ASCII codes for each character. If the two 
strings are not equal, the absolute value of variable i (or the result of the 
function ISCOMP) is the character position of the first inequality found. 
Strings are terminated by a null (0) character. 

If the strings are not the same length, the shorter one is treated as if it were 
padded on the right with blanks to the length of the other string. A null string 
argument is equivalent to a string containing only blanks. 

Function Results: 

i <0 If a is less than b. 
=0 If a is equal to b. 
>0 If a is greater than b. 

Example: 

LOGICAL*! INSTR(Bl) 
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CALL GETSTR(5 tINSTRtBO) 

CALL SCaMP( 'YES' tINBTR »IUAL) 

IF(IUAL.NE.O) GOTO 10 !IF INPUT STRING IS NOT YES GOTO 10 



3.97 SCOPY 



The SCOPY routine copies a character string from one array to another. 
Copying stops either when a null (0) character is encountered or when a 
specified number of characters have been moved. 

Form: CALL SCOPY (in,out[,len[,err]]) 

where: 

in is the array containing the string to be copied; it must be termi- 
nated with a null byte if len is not specified, or if the string is 
shorter than len 

out is the array to receive the copied string. This array m-ust be at 
least one element longer than the value of len, if len is specified. 
It also must be terminated with a null byte if len is specified 

len is the integer number representing the maximum length of the 
output string. The effect of len is to truncate the output string to 
a given length 

err is a logical variable that receives the error indication if the output 
string was truncated to the length specified by len 

The input (in) and output {out) arguments can specify the same array. The 
string previously contained in the output array is lost when this subroutine is 
called. 



Error conditions are indicated by err, if specified. If err is given and the 
output string was truncated to the length specified by len, then err is set 
to .TRUE.; otherwise, err is unchanged. 

Example: 

SCOPY is useful for initializing strings to a constant value, for example: 

L0GICAL*1 STRING (80) 

CALL SCDPY('THI5 IS THE INITIAL VALUE ' .STR I NG ) 



3.98 SECNDS 



The SECNDS function returns the current system time, in seconas past mia- 
night, minus the value of a specified argument. Thus, SECNDS can be used 
to calculate elapsed time. The value returned is single-precision floating point 
(REAL*4). 
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Form: a = SECNDS (atime) 

where: 

atime is a REAL*4 variable, constant, or expression whose value is 
subtracted from the current time of day to form the result 

Notes: 

This function does floating-point arithmetic. Elapsed time can also be calcu- 
lated by using the GTIM call and the INTEGER*4 support functions. 

Function Result: 

The function result (a) is the REAL*4 value returned. 

Errors: 

None. 

Example: 

C START OF TIMED SEQUENCE 

T1=SECNDS(0. ) 
C 

C CODE TO BE TIMED GOES HERE 
C 

DELTA=SECNDS(T1) "DELTA IS ELAPSED TIME 



3.99 SETCMD 



The SETCMD routine allows a user program to pass a command line to the 
keyboard monitor to be executed after the program exits. The command lines 
are passed to the chain information area (500-777, octal) and stored beginning 
at location 512(octal). No check is made to determine if the string extends 
into the stack space. For this reason, the command line should be short and 
the subroutine call should be made in the main program unit near the end of 
the program just before completion. When several commands are involved, an 
indirect command file that contains several command lines should be used. 

The monitor commands REENTER, START, and CLOSE are not allowed if 
the SETCMD feature is used. 

Form: CALL SETCMD (string) 

where: 

string is a keyboard monitor command line in ASCIZ format with no 
embedded carriage returns or line feeds 

Errors: 

None. 
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Example: 

LOGICAL*! fINPUK 134) .PROMPT (8) 

DATA PROMPT/ 'P ' . 'R' . '0' » 'M' . 'P' > 'T' » '> ' »"200/ 

CALL GTLIN ( INPUT . PROMPT ) 

CALL SETCMD (INPUT) 

END 

NOTE 

Set USR NOSWAP, or specify /NOSWAP with the COMPILE, 
FORTRAN, or EXECUTE command to control the swapping 
state of the USR. A LOCK would inhibit another job from 
using the USR. 

A STOP or CALL EXIT must also be issued for the SETCMD to cause an 
exit. 



3.100 STRPAD 



The STRPAD routine pads a character string with rightmost blanks until that 
string is a specified length. This padding is done in place; the result string is 
contained in its original array. If the present length of the string is greater 
than or equal to the specified length, no padding occurs. 

Form: CALL STRPAD (a,len[,err]) 

where: 

a is the array containing the string to be padded. This array must 
be one element longer than the value of len if len is specified. It 
will be terminated by a null byte 

len is the integer length of the desired result string 

err is the logical error flag that is set to .TRUE, if the string specified 
by a exceeds the value of i in length 



Errors: 



Error conditions are indicated by err, if specified. If err is given and the 
string indicated is longer than i characters, err is set to .TRUE.; other- 
wise, the value of err is unchanged. 



Example: 



This routine is especially useful for preparing strings to be output in 
A-type FORMAT fields. For example: 



LOGICAL*! STRC8!) 



CALL STRPAD(BTR .80) 'ASSURE 80 VALID CHARACTERS 
PRINT !00 .<STR( I ) »I=! .80) IPRINT STRING DP 80 CHARACTERS 
!00 FORMAT (BOA!) 
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3.101 SUBSTR 



The SUBSTR routine copies a substring from a specified position in a charac- 
ter string. If desired, the substring can then be placed in the same array as the 
string from which it was taken. 

Form: CALL SUBSTR (in,out,i[,lenj) 

where: 

in is the array from which the substring is taken; it is terminated by 
a null byte 

out is the array to contain the substring result. This array must be 
one element longer than len, if len is specified. It also is termi- 
nated by a null byte if len is specified 

i is the integer character position in the input string of the first 

character of the desired substring 

len is the integer number of characters representing the maximum 
length of the substring 

If a maximum length (len) is not given, the substring contains all characters 
to the right of character position i in array in and is not terminated by a null 
byte. If len is given, the string is copied and terminated with a null byte. If len 
is equal to zero, out is replaced by the null string. The old contents of array 
out are lost when this routine is called. 

Errors: 

None. 



3.102 SUSPND (FB and XM Only) 

The SUSPND subroutine suspends main program execution of the current job 
and allows only completion routines (for I/O and scheduling requests) to run. 

Form: CALL SUSPND 

Notes: 

1. The monitor maintains a suspension counter for each job. This count is 
decremented by SUSPND and incremented by RESUME (see Section 
3.94). A job will actually be suspended only if this counter is negative. 
Thus, if a RESUME is issued before a SUSPND, the latter routine will 
return immediately. 

2. A program must issue an equal number of SUSPND and RESUME calls. 

3. A SUSPND subroutine call from a completion routine decrements the 
suspension counter but does not suspend the main program. If a comple- 
tion routine does a SUSPND, the main program continues until it also 
issues a SUSPND, at which time it is suspended. Two RESUME calls are 
then required to proceed. 
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4. Because SUSPND and RESUME are used to simulate an ITWAIT (see 
Section 3.56) in the monitor, a RESUME issued from a completion rou- 
tine and not matched by a previously executed SUSPND can cause the 
main program execution to continue past a timed wait before the entire 
time interval has elapsed. 

For further information on suspending main program execution of the current 
job, see the .SPND programmed request (Section 2.77). 

Errors: 

None. 

Example: 

INTEGER lAREA(a) 

COMMON /RDBLK/ IBUF(25B) 

EXTERNAL RDFIN 



• r- . • ^, ■— n n F~ V j-j T- j-^ T r^ 1 1 r— T 15 1 ly t r^ i j /\ kl T A d •" A !~i P^ !*" T k 1 V WC Ti \ (—■ fl T H 1 / 

iFlIRLHUFCZ^btlDUl- jiDl_l\ tiL.nHhi*iHiti:ihfnijrii^j .iMt.v/ ■jL. lu i- 
C GOTO 1000 FOR ANY TYPE OF ERROR 

C 
C DO OMERLAPPED PROCESSING 



roil qiiqpND ISYNCHRONIZE WITH COMPLETION ROUTINE 



END 

SUBROUTINE RDFirJt lARGl »IARGZ) 

COMMON /RDBLK/ IBUF(25B) 



CALL RESUME ! CONTINUE MAIN PROGRAM 



END 



3.103 TIMASC 

The TIMASC subroutine converts a two-word internal format time into an 
ASCII string of the form: 

hh:mm:ss 

where: 

hh is the two-digit hours indication 

mm is the two-digit minutes indication 

ss is the two-digit seconds indication 
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Form: CALL TIMASC (itime,strng) 

where: 

itime is the two-word internal format time to be converted, itime (1) 
is the high-order time, itime (2) is the low-order time 

strng is the eight-element array to contain the ASCII time 

Errors: 

None. 

Example: 

The following example determines the amount of time from the time 
the program is run until 5 p.m. and prints it. 

INTEGER*^ Jl *J2 .J3 
LOGICAL*! BTRNG(B) 



CALL JTIME( 17.0 .0 .0 »J1) 
CALL GTIM(J2) 
CALL JJCUT(Jl) 
CALL JJCMTCJZ) 
CALL JSUB( Jl »J2 .J3) 
CALL JJCUT(J3) 
CALL TIHASC( J3 tSTRNG) 
TYPE 99 ,{STRNG( I ) ,1 = 1 ,8) 
99 format;' it is ',8A1,' till 5 P.M.') 



3.104 TIME 

The TIME subroutine returns the current system time of day as an eight- 
character ASCII string of the form: 

hh:mm:ss 

where: 

hh is the two-digit hours indication 

mm is the two-digit minutes indication 

ss is the two-digit seconds indication 
Form: CALL TIME (strng) 
where: 

strng is the eight-element array to receive the ASCII time 

Notes: 

A 24-hour clock is used (for example, 1:00 p.m. is represented as 13:00:00). 
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Errors: 

None. 
Example: 



LOGICAL*! STRNG(S) 



CALL TIME(STRNG) 
TYPE 99 ,(STRNG( I) .1 = 1 *8) 
99 FORMAT (' IT IS NOW '>SA1) 



3.105 TRANSL 



The TRANSL routine performs character translation on a specified string and 
requires approximately 64 decimal words on the R6 stack for its execution. 
This space should be considered when allocating stack space. 

where; 

in is the array containing the input string; it is terminated by a null 
byte 

out is the array to receive the translated string; it is not terminated 
by a null byte 

r is the array containing the replacement string; it is terminated by 

a null byte 

p is the array containing the characters in in to be translated; it is 
terminated by a null byte 

The string specified by array out is replaced by the string specified by array 
in, modified by the character translation process specified by arrays r and p. If 
any character position in in contains a character that appears in the string 
specified by p, it is replaced in out by the corresponding character from string 
r. If the array p is omitted, it is assumed to be the 127 seven-bit ASCII 
characters arranged in ascending order, beginning with the character whose 
ASCII code is 001. If strings r and p are given and differ in length, the longer 
string is truncated to the length of the shorter. If a character appears more 
than once in strmg p, only the last occurrence is significant. A character can 
appear any number of times in string r. 

Errors: 

None. 

Examples: 

The following example causes the string in array A to be copied to array 
B. All periods within A become minus signs, and all question marks 
become exclamation points. 

CALL TRANBL(A»B t '-!'.'.?' ) 
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The following is an example of TRANSL being used to format character 
data. 



LOGICAL*! STRING(27) >RESULT(27) ,PATRN(27) 
SET UP THE STRING TO BE REFORMATTED 

CALL SCDPY('THE HORN BLOWS AT M IDN I GHT ' fSTR ING ) 
SET UP NUMBER-CHARACTER DATA RELATIONSHIP 



000000000 111111111 1 2222222 

12345878901234567890123456 

THE HORN BLOWS AT MIDNIGHT 

NOW SET UP PATRN TO CONTAIN THE FOLLOWING PATTERN: 

IG .17 »18 .19,20,21 ,22 ,23 »24 .25 .28 .15 (1 ,2 t3 ,4 .5 ,G .7!8 ,9 ,10 .11 ,12 ,13 tl4 »0 



DO 10 I =16,28 
10 PATRN( I-15)=I 

PATRNf 12)=15 

DO 20 1=1,14 
20 PATRNC I+12)=I 

PATRN (27) =0 



THE FOLLOWING CALL TO TRANSL REARRANGES THE CHARACTERS OF 
THE INPUT STRING TO THE ORDER SPECIFIED BY PATRN: 

CALL TRANSL(PATRN , RESULT , STRING) 

RESULT NOW CONTAINS THE STRING 'AT MIDNIGHT THE HORN BLOWS' 
IN GENERAL, THIS METHOD CAN BE USED TO FORMAT INPUT STRINGS 
OF UP TO 127 CHARACTERS. THE RESULTANT STRING WILL BE 
AS LONG AS THE PATTERN STRING (AS IN THE ABQOE EXAMPLE), 



3.106 TRIM 



The TRIM routine shortens a specified character string by removing all trail- 
ing blanks. A trailing blank is a blank that has no non-blanks to its right. If 
the specified string contains all blank characters, it is replaced by the null 
string. If the specified string has no trailing blanks, it is unchanged. 

Form: CALL TRIM (a) 



where: 



is the array containing the string to be trimmed; it is terminated by 
a null byte on input and output 



Errors: 

None. 
Example: 



L0GICAL#1 STRING(81) 
ACCEPT 100 ,( STRING ( I) ,1 = 1 .80) 
100 FORMAT ( 80A1 ) 

CALL SCOPY(STRING .STRING ,80) 
CALL TRIM( STRING) 



MAKE ASCIZ 

TRIM TRAILING BLANKS 
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3.107 UNLOCK 



The UNLOCK subroutine releases the User Service Routine (USR) from 
memory if it was placed there by the LOCK routine. If the LOCK required a 
swap, the UNLOCK loads the user program back into memory. If the USR 
does not require swapping, the UNLOCK involves no I/O. The USR is always 
resident in XM. 

Form: CALL UNLOCK 

Notes: 

1. It is important that at least as many UNLOCK calls are given as LOCK 
calls. If more LOCK calls were done, the USR remains locked in memory. 
Extra UNLOCK calls are ignored. 

2. When running two jobs in the FB system, use the LOCK/UNLOCK pairs 
only when absolutely necessary. If one job locks the USR, the other job 
cannot use the USR until it is unlocked. 

3. In an FB system, calling the CSI (ICSI) with input coming from the 
console terminal performs a temporary implicit UNLOCK. 

For further information on releasing the USR from memory, see the 
.LOCK/.UNLOCK programmed requests (Section 2.39). 

Errors: 

None. 
Exam^ple: 



rii — r r-ii— Ar\\/ t n r^n iui/\mv/ ifCI^ nDETrJATTHhlO 
\jC i ITCMLJ i i U UU rini^ l lj O it lj i i_i\n i alji^vj 

CALL LOCK iDISABLE USR SWAPPING 
PERFORM THE USR CALLS 



FREE THE USR 
CALL UNLOCK 



3.108 VERIFY 



The VERIFY routine checks that a given string is composed entirely of char- 
acters from a second string. If a character does not exist in the string being 
examined, VERIFY returns the position of the first character in the string 
being examined that is not in the source string. If all characters exist, 
VERIFY returns a 0. 
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Form: CALL VERIFY (a,b,i) 
or 
i = IVERIF (a,b) 
where: 

a is the array containing the string to be scanned; it is terminated by 
a null byte 

b is the array containing the string of characters to be accepted in a; 
it is terminated by a null byte 

Function Result: 

i = If all characters of a exist in 6; also if a is a null string. 
= n Where n is the character position of the first character in array 
a that does not appear in array 6; if 6 is a null string and a is 
not, i equals 1. 

Example: 

The following example accepts a one- to five-digit unsigned decimal 
number and returns its value. 

LOGICAL*! INSTR(81) 



CALL UERIFY( INSTR , '0123^56789' ,1 ) 
IFd.EO.n STOP 'NUMBER MISSING' 
IF(I.EO.O) I=LEN(INSTR) 
IF(I.GT,5) STOP 'TOO MANY DIGITS' 
NUM=IUALUE( INSTR .1 ) 



END 
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Appendix A 
Display File Handler 



This appendix describes the assembly language support provided under 
RT-11 for the VTll graphic display hardware systems. 

The following manuals are suggested for additional reference: 

GT40/GT42 User's Guide 
EK-GT40-OP-002 

GT44 User's Guide 

EK-GT44-OP-001 

VTll Graphic Display Processor 
EK-VTll-TM-001 

DECGRAPHIC-11 GT Series Reference Card 
EH-02784-73 

DECGraphic-11 FORTRAN Reference Manual 
DEC-11-GFRMA-A-D 

BASIC-11 Graphics Extensions User's Guide 
DEC-11-LBGEA-A-D 



A.1 Description 



The graphics display terminals have hardware configurations that include a 
display processor and CRT (cathode ray tube) display. All systems are 
equipped with light pens and hardware character and vector generators, and 
are capable of high-quality graphics. The Display File Handler supports this 
graphics hardware at the assembly language level under the RT-11 monitor. 

A.1.1 Assembly Language Display Support 

The Display File Handler is not an RT-11 device handler, since it does not use 
the I/O structure of the RT-11 monitor. For example, it is not possible to use a 
utility program to transfer a text file to the display through the Display File 
Handler. Rather, the Display File Handler provides the graphics programmer 
the means for the display of graphics files and the easy management of the 
display processor. Included in its capabilities are such services as interrupt 
handling, light pen support, tracking object, and starting and stopping of the 
display processor. 

The Display File Handler manages the display processor by means of a base 
segment (called VTBASE) which contains interrupt handlers, an internal 
display file and some pointers and flags. The display processor cycles through 
the internal display file; any user graphics files to be displayed are accessed 
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by display subroutine calls from the Handler's display file. In this way, the 
Display File Handler exerts control over the display processor, relieving the 
assembly language user of the task. 

Through the Display File Handler, the programmer can insert and remove 
calls to display files from the Handler's internal display file. Up to two user 
files may be inserted at one time, and that number may be increased by re- 
assembling the Handler. Any user file inserted for display may be blanked 
(the subroutine call to it bypassed) and unblanked by macro calls to the 
Display File Handler. 

Since the Handler treats all user display files as graphics subroutines to its 
internal display file, a display processor subroutine call is required. This 
is implemented with software, using the display stop instruction, and 
is available for user programs. This instruction and several other extended 
instructions implemented with the display stop instruction are described in 
Section A. 3. 

The facilities of the Display File Handler are accessed through a file of macro 
definitions (VTMAC) which generate calls to a set of subroutines in VTLIB. 
VTMAC's call protocol is similar to that of the RT-11 macros. The expansion 
of the macros is shown in Section A.6. VTMAC also contains, for convenience 
in programming, the set of recommended display processor instruction 
mnemonics and their values. The mnemonics are listed in Section A.7 and are 
used in the examples throughout this appendix. 

VTCALl through VTCAL4 are the set of subroutines which service the 
VTMAC calls. They include functions for display file and display processor 
management. These are described in detail in Section A.2. VTCALl through 
VTCAL4 are distributed, along with the base segment VTBASE, as a file of 
five object modules called VTHDLR.OBJ. VTHDLR is built into the graphics 
library VTLIB by using the monitor LIBRARY command. VTHDLR only 
supports VTll hardware. Section A.4.2 shows an example. 



A.1.2 Monitor Display Support 

The RT-11 monitor, under Version 03 and later, directly supports the display 
as a console device. A keyboard monitor command, GT ON (GT OFF) per- 
mits the selection of the display as console device. Selection results in the 
allocation of approximately 1.25K words of memory for text buffer and code. 
The buffer holds approximately 2000 characters. 

The text display includes a blinking cursor to indicate the position in the text 
where a character is added. 1 he cursor initially appears at the top left corner 
of the text area. As lines are added to the text the cursor moves down the 
screen. When the maximum number of lines are on the screen, the top line is 
deleted from the text buffer when the line feed terminating a new line is 
received. This causes the appearance of "scrolling," as the text disappears off 
the top of the display. 

When the maximum number of characters have been inserted in the text 
buffer, the scroller logic deletes a line from the top of the screen to make room 
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for additional characters. Text may appear to move (scroll) off the top of the 
screen while the cursor is in the middle of a line. 

The Display File Handler can operate simultaneously with the scroller pro- 
gram, permitting graphic displays and monitor dialogue to appear on the 
screen at the same time. It does this by inserting its internal display file into 
the display processor loop through the text buffer. However, the following 
should be noted. Under the SJ Monitor, if a program using the display for 
graphics is running with the scroller in use (that is, GT ON is in effect), and 
the program does a soft exit (.EXIT with RO not equal to 0) with the display 
stopped, the display remains stopped until a CTRL/C is typed at the key- 
board. 

This can be recognized by failure of the monitor to echo on the screen when 
expected. If the scroller text display disappears after a program exit, always 
type CTRL/C to restore. If CTRL/C fails to restore the display, the running 
program probably has an error. 

Four scroller control characters provide the user with the capability of halting 
the scroller, advancing the scrolling in page sections, and printing hard copy 
from the scroller. 

NOTE 

The scroller logic does not limit the length of a line, but the 
length of text lines affects the number of lines which may be 
displayed, since the text buffer is finite. As text lines become 
longer, the scroller logic may delete extra lines to make room 
for new text, temporarily decreasing the number of lines dis- 
played. 



A.2 Description of Graphics IVIacros 

The facilities of the Display File Handler are accessed through a set of macros, 
contained in VTMAC, which generate assembly language calls to the Handler 
at assembly time. The calls take the form of subroutine calls to the sub- 
routines in VTLIB. Arguments are passed to the subroutines through register 
and, in the case of the .TRACK call, through both register and the stack. 

This call convention is similar to Version 1 RT-11 I/O macro calls, except that 
the subroutine call instruction is used instead of the EMT instruction. If a 
macro requires an argument but none is specified, it is assumed that the 
address of the argument has already been placed in register 0. The program- 
mer should not assume that RO is preserved through the call. 

A.2.1 .BLANK 

The .BLANK request temporarily blanks the user display file specified in the 
request. It does this by bypassing the call to the user display file, which 
prevents the display processor from cycling through the user file, effectively 



Appendix A-3 



blanking it. This effect can later be canceled by the .RESTR request, which 
restores the user file. When the call returns, the user is assured the display 
processor is not in the file that was blanked. 

Macro Call: .BLANK faddr 

where: 



faddr is the address of the user display file to be blanked 



Errors: 



No error is returned. If the file specified was not found in the Handler 
file or has already been blanked, the request is ignored. 



A.2.2 .CLEAR 

The .CLEAR request initializes the Display File Handler, clearing out any 
calls to user display files and resetting all of the internal flags and pointers. 

After initialization with .LNKRT (Section A.2.4), the .CLEAR request can be 
used any time in a program to clear the display and to reset pointers. All calls 
to user files are deleted and all pointers to status buffers are reset. They must 
be re-inserted if they are to be used again. 

Macro Call: .CLEAR 

Errors: 



None. 
Example: 



This example uses a .CLEAR request to initialize the Handler then 
later uses the .CLEAR to re-initialize the display. The first .CLEAR is 
used for the case when a program may be restarted after a CTRL C or 
other exit. 



BR RSTRT 

EXi: BIS #20000f@#44 
RSTRT : .UNLNK 

.LNKRT 

.CLEAR 

.INSRT #FILE1 
1*: .TTYIN 

CMPB *12»R0 

BNE 1* 

.CLEAR 

.INSRT tFILEl' 



tSET REENTER BIT IN JSU 

; CLEARS LINK FLAG FOR RESTART 

J SET UP UECTORSr START riT<5Pi av 

5 INITIALIZE HANDLER 

5 DISPLAY A PICTURE 

JWAIT FOR A KEY STRIKE 

fLINE FEED? 

jnot- loop 

jyesf clear display 

; display new picture 



FILEi: 



POINT 



500 

LONGV 

500!INTX 



DRET 





»AT POINT <0r500) 



rDRAW A LINE 
rTO (500,500) 
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FILE2! 



POINT 


fAT POINT <50 


500 









LONGV 


fliRAy A LINE 


0! INTX 


rTO <500i-500) 


500 




tiRET 









.END EXl 





A.2.3 .INSRT 

The .INSRT request inserts a call to the user display file specified in the 
request into the Display File Handler's internal display file. .INSRT causes 
the display processor to cycle through the user file as a subroutine to the 
internal file. The handler permits two user files at one time. The call inserted 
in the handler looks like the following: 

DJSR jDISPLAY SUBROUTINE 

,+4 ? RETURN ADDRESS 

.f3ddr ^SUBROUTINE ADDRESS 

The call to the user file is removed by replacing its address with the address of 
a null display file. The user file is blanked by replacing the DJSR with a 
DJMP instruction, bypassing the user file. 

Macro Call: .INSRT faddr 

where: 

faddr is the address of the user display file to be inserted 

Errors: 

The .INSRT request returns with the C bit set if there was an error in 
processing the request. An error occurs only when the Handler's display 
file is full and cannot accept another file. If the user file specified exists, 
the request is not processed. Two display files with the same starting 
address cannot be inserted. 

Example: 

See the examples in Sections A. 2. 2 and A. 2.4. 

A.2.4 .LNKRT 

The .LNKRT request sets up the display interrupt vectors and possibly links 
the Display File Handler to the scroll text buffer in the RT-U monitor. It 
must be the first call to the Handler, and is used whether or not the RT-11 
monitor is using the display for console output (that is, the KMON command 
GT ON has been entered). 

The .LNKRT request used with Version 03 and later RT-11 monitors enables 
a display application program to determine the environment in which it is 
operating. Error codes are provided for the situations where there is no display 
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hardware present on the system or the display hardware is already being used 
by another task (for example, a foreground job in the foregroundA)ackground 
version). 

The existence of the monitor scroller and the size of the Handler's subpicture 
stack are also returned to the caller. If a previous call to .LNKRT was made 
without a subsequent .UNLNK, the .LNKRT call is ignored and an error code 
is returned. 

Macro Call: .LNKRT 

Errors: 

Error codes are returned in RO, with the N condition bit set. 

Code Meaning 

-1 No VTll display hardware is present on this system. 

-2 VTll hardware is presently in use. 

-3 Handler has already been linked. 

On completion of a successful .LNKRT request, RO will contain the 
display subroutine stack size, indicating the depth to which display 
subroutines may be nested. The N bit will be zero. 

If the RT-11 monitor scroll text buffer was not in memory at the time of 
the .LNKRT, the C bit will be returned set. The KMON commands GT 
ON and GT OFF cannot be issued while a task is using the display. 

Example: 



start: 



cont: 



i*j 



sbuf: 



FILEi: 



ERROR : 



.LNKRT 




5LINK TO MONITOR 


BMI 


ERROR 


JERROR DOING LINK 


BCS 


CONT 


»N0 SCROLL IF C SET 


.SCROL 


#SBUF 


.ADJUST SCROLL PARAMETERS 


.INSRT 


♦FILEI 


fDISPLAY A PICTURE 


.TTYIN 




JUAIT FOR KEY STRIKE 


CMPB 


#12, RO 


J LINE FEED? 


BNE 


1* 


iHOf LOOP 


, UNLNK 




iYES, UNLINK AND EXIT 


.EXIT 






.BYTE 


5 


5LINE COUNT OF 5 


.BYTE 


7 


5 INTENSITY 7 (SCALE OF 1- 


.WORD 


1000 


5P0SITI0N OF TOP LINE 


POINT 




;AT point <500»500) 


500 






500 






CHAR 




5 DISPLAY SOME TEXT 


.ASCII 


/FILEI THIS 


IS FILEI. TYPE CR TO EXIT, 


.EVEN 






BRET 







Error routine 





8) 
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A.2.5 .LPEN 

The .LPEN request transfers the address of a light pen status data buffer to 
VTBASE. Once the buffer pointer has been passed to the Handler, the light 
pen interrupt handler in VTBASE will transfer display processor status data 
to the buffer, depending on the state of the buffer flag. 

The buffer must have seven contiguous words of storage. The first word is the 
buffer flag, and it is initially cleared (set to zero) by the .LPEN request. When 
a light pen interrupt occurs, the interrupt handler transfers status data to the 
buffer and then sets the buffer flag non-zero. The program can loop on the 
buffer flag when waiting for a light pen hit (although doing this will tie up the 
processor; in a foreground/background environment, timed waits would be 
more desirable). No further data transfers take place, despite the occurrence 
of numerous light pen interrupts, until the buffer flag is again cleared to zero. 
This permits the program to process the data before it is destroyed by another 
interrupt. 

The buffer structure looks like this: 

Buffer Flag 

Name 

Subpicture Tag 

Display Program Counter (DPC) 

Display Status Register (DSR) 

X Status Register (XSR) 

Y Status Register (YSR) 

The Name value is the contents of the software Name Register (described in 
A.3.5) at the time of interrupt. The Tag value is the tag of the subpicture 
being displayed at the time of interrupt. The last four data items are the 
contents of the display processor status registers at the time of interrupt. They 
are described in detail in Table A-1. 

Macro Call: .LPEN baddr 

where: 

baddr is the address of the 7-word light pen status data buffer 
Errors: 

None. 

If a .LPEN was already issued and a buffer specified, the new buffer 
address replaces the previous buffer address. Only one light pen buffer 
can be in use at a time. 

Example: 



.INSRT 


tLFILE 


JIIISPLAY LFILE 


. LPEN 


*LBUF 


5 SET UP LPEN BUFFER 


loop: TST 


LBUF 


STEST LBUF FLAGt WHICH 


BEQ 


LOOP 


fWILL BE SET NON-ZERO 
JON LIGHT PEN HIT. 


f PROCESS DATA IN 


LBUF HERE. 
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5 DATA IN LBUF 




CLR 


LBUF 


? CLEAR THE BUFFER FLAG 
JPERMITTING ANOTHER "HIT 




BR 


LOOP 


fGO WAIT FOR IT 


lbuf: 


.BLKU 


7 


5 SEVEN WORD LPEN BUFFER 


lfile: 









Table A-1: Description of Display Status Words 



Bits 


Signiflcance 


Display Program Counter (DPC= 


172000) 


0-15 


Address of display processor program 
counter at time of interrupt. 


Display Status Register (DSR=172002) 


0-1 

2 

3 


Line Type 

Spare 

Blink 


4 


Italics 


5 
6 


Edge Indicator 
Shift Out 


7 

8-10 

11-14 


Light Pen Flag 

Intensity 

Mode 


15 


Stop Flag 


X Status Register (XSR=172004) 




0-9 


X Position 


10-15 


Graphplot Increment 


Y Status Register (YSR=172006) 




0-9 


Y Position 


10-15 


Character Register 



A.2.6 .NAME 

The .NAME request has been added to the Version 03 and later Display File 
Handler. The contents of the name register are now stacked when a subpic- 
ture call is made. When a light pen interrupt occurs, the contents of the name 
register stack may be recovered if the user program has supplied the address 
of a buffer through the .NAME request. 

The buffer must have a size equal to the stack depth (default is 10) plus one 
word for the flag. When the .NAME request is entered, the address of the 
buffer is passed to the Handler and the first word (the flag word) is cleared. 
When a light pen hit occurs, the stack's contents are transferred and the flag 
is set non-zero. 

Macro Call: .NAME baddr 



where: 



baddr is the address of the name register buffer 



A-8 Appendix 



Errors: 

None. 

If a .NAME request has been previously issued, the new buffer address 
replaces the previous buffer address. 

A.2.7 .REMOV 

The .REMOV request removes the call to a user display file previously in- 
serted in the handler's display file by the .INSRT request. All reference to the 
user file is removed, unlike the .BLANK request, which merely bypasses the 
call while leaving it intact. 

Macro Call: .REMOV faddr 

where: 

faddr is the address of the display file to be removed 

Errors: 

No errors are returned. If the file address given cannot be found, the 
request is ignored. 

A.2.8 .RESTR 

The .RESTR request restores a user display file that was previously blanked 
by a .BLANK request. It removes the by-pass of the call to the user file, so 
that the display processor once again cycles through the user file. 

Macro Call: .RESTR faddr 

where: 

faddr is the address of the user file that is to be restored to view 

Errors: 

No errors are returned. If the file specified cannot be found, the request 
is ignored. 

A.2.9 .SCROL 

This request is used to modify the appearance of the Display Monitor's text 
display. The .SCROL request permits the programmer to change the maxi- 
mum line count, intensity and the position of the top line of text of the 
scroller. The request passes the address of a two-word buffer which contains 
the parameter specifications. The first byte is the line count, the second byte 
is the intensity, and the second word is the Y position. Line count, intensity 
and Y position must all be octal numbers. The intensity may be any number 

r_^ — A i-„ r7 : c j; 4- j-„ 'U^i^i.i.^^-t- /jr — . ;«+« — :^,. «-f r\ ^« «■. — ^^ 

iiuiii V i,u I , ranging injITi umiiucot lu urigiitcnL. V" aH iiiLeiioity ui u 10 opcui- 

fied, the scroller text will be almost unnoticeable at a BRIGHTNESS knob 
setting less than one-half.) The scroller parameter change is temporary, since 
an .UNLNK or CTRL/C restores the previous values. 
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Macro Call: .SCROL baddr 



where: 



baddr is the address of the two-word scroll parameters buffer 



Errors: 



No errors are returned. No checking is done on the values of the param- 
eters. A zero argument is interpreted to mean that the parameter value 
is not to be changed. A negative argument causes the default parameter 
value to be restored. 



Example: 



.SCROL 



#SCBUF 



f ADJUST SCROLL PARAMETERS 



scbuf: 



.BYTE 5 
.BYTE 
.WORD 300 



^DECREASE *LINES TO 5. 

f LEAVE INTENSITY UNCHANGED. 

J TOP LINE AT Y=300. 



A.2.10 .START 

The .START request starts the display processor if it was stopped by a .STOP 
directive. If the display processor is running, it is stopped first, then restarted. 
In either case, the subpicture stack is cleared and the display processor is 
started at the top of the handler's internal display file. 

Macro Call: .START 

Errors: 

None. 

A.2.11 .STAT 

The .STAT request transfers the address of a seven-word status buffer to the 
display stop interrupt routine in VTBASE. Once the transfer has been made, 
display processor status data is transferred to the buffer by the display stop 
interrupt routine in VTBASE whenever a .DSTAT or .DHALT instruction is 
encountered (see Sections A. 3. 3 and A.3.4). The transfer is made only when 
the buffer flag is clear (zero). After the transfer is made, the buffer flag is set 
non-zero and the .DSTAT or .DHALT instruction is replaced by a .DNOP 
(Display NOP) instruction. 

The status buffer must be a seven-word, contiguous block of memory. Its 
contents are the same as the light pen status buffer. For a detailed description 
of the buffer and an explanation of the status words, see Section A. 2. 5 and 
Table A-1. 

Macro Call: .STAT baddr 

where: 

baddr is the address of the status buffer receiving the data 
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Errors: 

No errors are indicated. If a buffer was previously set up, the new buffer 
address is replaced as the old buffer address. 

A.2.12 .STOP 

The .STOP request "stops" the display processor. It actually effects a stop by 
preventing the DPU from cycling through any user display files. It is useful for 
stopping the display during modification of a display file, a risky task when 
the display processor is running. However, a .BLANK could be equally useful 
for this purpose, since the .BLANK request does not return until the display 
processor has been removed from the user display file being blanked. 

Macro Call: .STOP 

Errors: 

None. 

NOTE 

Since the display processor must cycle through the text buffer 
in the Display Monitor in order for console output to be pro- 
cessed, the text buffer remains visible after a .STOP request is 
processed, but all user files disappear. 

A.2.13 .SYNC/.NOSYN 

The .SYNC and .NOSYN requests provide program access to the power line 
synchronization feature of the display processor. The .SYNC request enables 
synchronization and the .NOSYN request disables it (the default case). 

Synchronization is achieved by stopping the display and restarting it when 
the power line frequency reaches a trigger point, e.g., a peak or zero- crossing. 
Synchronization has the effect of fixing the display refresh time. This may be 
useful in some cases where small amounts of material are displayed but the 
amount frequently changes, causing changes in intensity. In most cases, how- 
ever, using synchronization increases flicker. 

Macro Calls: .SYNC 
.NOSYN 

Errors: 

None. 

A.2.14 .TRACK 

The .TRACK request causes the tracking object to appear on the display CRT 
at the position specified in the request. The tracking object is a diamond- 
shaped display figure which is light-pen sensitive. If the light pen is placed 
over the tracking object and then moved, the tracking object follows the light 
pen, trying to center itself on the pen. 
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The tracking object first appears at a position specified in a two-word buffer 
whose address was supplied with the .TRACK request. As the tracking object 
moves to keep centered on the Hght pen, the new center position is returned 
to the buffer. A new set of X and Y values is returned for each light pen 
interrupt. 

The tracking object cannot be lost by moving it off the visible portion of the 
display CRT. When the edge flag is set, indicating a side of the tracking object 
is crossing the edge of the display area, the tracking object stops until moved 
toward the center. To remove the tracking object from the screen, repeat the 
.TRACK request without arguments. 

The .TRACK request may also include the address of a completion routine as 
the second argument. If a .TRACK completion routine is specified, the light 
pen interrupt handler passes control to the completion routine at interrupt 
level. The completion routine is called as a subroutine and the exit statement 
must be an RTS PC. The completion routine must also preserve any registers 
it may use. 

Macro Call: .TRACK baddr, croutine 

where: 

baddr is the address of the two- word buffer containing the X and Y 
position for the track object 

croutine is the address of the completion routine 

Errors: 

None. 

Example: 

See Section A. 10. 

A.2.15 .UNLNK 

The .UNLNK request is used before exiting from a program. In the case where 
the scroller is present, .UNLNK breaks the link, established by .LNKRT, 
between the Display File Handler's internal display file and the scroll file in 
the Display Monitor. The display processor is started cycling in the scroll text 
buffer, and no further graphics may be done until the link is established 
again. In the case where no scroller exists, the display processor is simply left 
stopped. 

Macro Call: .UNLNK 

Errors: 

No errors are returned. An internal link flag is checked to determine if 
the link exists. If it does not exist, the request is ignored. 
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A. 3 Extended Display Instructions 

The Display File Handier offers tiie assembiy language grapiiics programmer 
an extended display processor instruction set, implemented in software 
through the use of the Load Status Register A (LSRA) instruction. The ex- 
tended instruction set includes: subroutine call, subroutine return, display 
status return, display halt, and load name register. 

A. 3.1 DJSR Subroutine Call Instruction 

The DJSR instruction (octal code is 173400) simulates a display subroutine 
call instruction by using the display stop instruction (LSRA instruction with 
interrupt bits set). The display stop interrupt handler interprets the non-zero 
word following the DJSR as the subroutine return address, and the second 
word following the DJSR as the address of the subroutine to be called. The 
instruction sequence is: 

DJSR 

Return address 

Subroutine address 

Example: 

To call a subroutine SQUARE: 

POINT JPOSITION BEAM 

100 5AT (lOOflOO) 

100 

lUSR STHEN CALL SUBROUTINE 

.+4 

SQUARE rTO DRAW A SQUARE 

DRET 



The use of the return address preceding the subroutine address offers 
several advantages. For example, the BASIC-11 graphics software uses 
the return address to branch around subpicture tag data stored follow- 
ing the subpicture address. This structure is described in Section A. 5. 3. 
In addition, a subroutine may be temporarily bypassed by replacing the 
DJSR code with a DJMP instruction, without the need to stop the 
display processor to make the by-pass. 

The address of the return address is stacked by the display stop inter- 
rupt handler on an internal subpicture stack. The stack depth is condi- 
tionalized and has a default depth of 10. If the stack bottom is reached, 
the display stop interrupt handler attempts to protect the system by 
rejecting additional subroutine calls. In that case, the portions of the 
display exceeding the legal stack depth will not be displayed. 

A. 3. 2 DRET Subroutine Return Instruction 

The DRET instruction provides the means for returning from a display file 
subroutine. It uses the same octal code as DJSR, but with a single argument 
of zero. The DRET instruction causes the display stop interrupt handler to 
pop its subpicture stack and fetch the subroutine return address. 
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Example: 
square: 



LONGV 

lOOIINTX 



OIINTX 

100 

lOOIINTXIMINUSX 



OIINTX 

lOOIMINUSX 

DRET 





KiRAU A SQUARE 



RETURN FROM SUBPICTURE 



A.3.3 DSTAT Display Status Instruction 

The DSTAT instruction (octal code is 173420) uses the LSRA instruction to 
produce a display stop interrupt, causing the display stop interrupt handler to 
return display status data to a seven-word user status buffer. The status 
buffer must first have been set up with a .STAT macro call (if not, the 
DSTAT is ignored and the display is resumed). The first word of the buffer is 
set non-zero to indicate the transfer has taken place, and the DSTAT is 
replaced with a DNOP (display NOP). The first word is the buffer flag and 
the next six words contain name register contents, current subpicture tag, 
display program counter, display status register, display X register, and dis- 
play Y register. After transfer of status data, the display is resumed. 



A.3.4 DHALT Display Halt Instruction 

The DHALT instruction (octal code is 173500) operates similarly to the 
DSTAT instruction. The difference between the two instructions is that the 
DHALT instruction leaves the display processor stopped when exiting from 
the interrupt. A status data transfer takes place provided the buffer was 
initialized with a .STAT call. If not, the DHALT is ignored. 

Example: 



1*: 



.STAT 
MOV 
.INSRT 
TST 

BEQ 



♦SBUF 

#nHALT»STPLOC 

#DFILE 

SBUF 

1$ 



JINIT BUFFER 
» INSERT DHALT 
^DISPLAY THE PICTURE 
r DHALT PROCESSED? 
JNO» WAIT 



sbuf: 
dfile: 



STPLOCJ 



.6LKU 

POINT 

.WORD 

LONOy 

.UORD 

DNOP 

DRET 





500t1350 
0»400 



r STATUS BUFFER 

Jf'OSITION NEAR TOP OF 12" TUBE 

fDRAW A LINEr MAYBE OVER EDGE 
;iF IT IS A 12" SCOPE. 
5 STATUS WILL BE RETURNED AT 
fTHIS POINT 



A. 3. 5 DNAIVIE Load Name Register Instruction 

The Display File Handler provides a name register capability through the use 
of the display stop interrupt. When a DNAME instruction (octal code is 
173520) is encountered, a display stop interrupt is generated. The display stop 
handler stores the argument following the DNAME instruction in an internal 
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software register called the "name register." The current name register con- 
tents are returned whenever a DSTAT or DHALT is encountered, and more 
importantly, whenever a light pen interrupt occurs. The use of a "name" 
(with a valid range from 1 to 77777) enables the programmer to label each 
element of the display file with a unique name, permitting the easy identifica- 
tion of the particular display element selected by the light pen. 

The name register contents are stacked on a subpicture call and restored on 
return from the subpicture. 

Example: 

The SQUARE subroutine with "named" sides. 



square: dname jname is 

10 f 10 

LONGM fDRAU A SIDE 

lOOIINTX 



DNAME »THIS SIDE IS NAMED 

11 ;il 

OIINTX » STILL IS LONG VECTOR MODE 

100 

DNAME 

12 

lOOIINTXIMINUSX 



DNAME 

13 

OIINTX 

lOOIMINUSX 

DRET 5 RETURN FROM SUBPICTURE 





A. 4 Using the Display File Handler 

Graphics programs which intend to use the Display File Handler for display 
processor management can be written in MACRO assembly language. The 
display code portions of the program may use the mnemonics described in 
Section A.7. Calls to the Handler should have the format described in 
Section A.6. 

The Display File Handler is supplied in two pieces, a file of MACRO defini- 
tions and a library containing the Display File Handler modules. 

MACRO Definition File: VTMAC.MAC 

Display File Handler: VTLIB.OBJ (consisting of:) 

VTBASE.OBJ 
VTCALl.OBJ 
VTCAL2.0BJ 
VTCAL3.0BJ 
VTCAL4.0BJ 
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A.4.1 Assembling Graphics Programs 

To assemble a graphics program using the display processor mnemonics or the 
Display Handler macro calls, the file VTMAC.MAC must be assembled with 
the program, and must precede the program in the assembler command 
string. 

Example: 

Assume PICTUR.MAC is a user graphics program to be assembled. An 
assembler command string would look like this: 

MACRO yTMAC+PICTUR/OBJECT 

A. 4. 2 Linl<ing Graphics Programs 

Once assembled with VTMAC, the graphics program must be linked with the 
Display File Handler, which is supplied as a single concatenated object mod- 
ule, VTHDLR.OBJ. The Handler may optionally be built as a library, follow- 
ing the directions in A.8.5. The advantage of using the library when linking is 
that the Linker will select from the library only those modules actually used. 
Linking with VTHDLR.OBJ results in all modules being included in the link. 

To link a user program called PICTUR.OBJ using the concatenated object 
module supplied with RT-11: 

LINK PICTUR»VTHDLR 

To link a program called PICTUR.OBJ using the VTLIB library built by 
following the directions in A.8.5, be sure to use the Version 03 Linker: 

LINK PICTUR»yTLIB 



VTLIB (Handler Modules): 

Module CSECT Contains 



VTCALl $GT1 

.STOP 

VTCAL2 $GT2 

VTCAL3 $GT3 



VTCAL4 $GT4 



VTBASE $GTB 



.CLEAR 

.START 

$VSTOP 

.INSRT 

.REMOV 

.BLANK 
.RESTR 

.LPEN 

.NAME 

.STAT 

.SYNC 

.NOSYN 

•TRACK 

.LNKRT 
.UNLNK 
.SCROL 

Interrupt handler 
and internal 
display file 



Globals 

$VINIT 
$VSTRT 

$VNSRT 
$VRMOV 

$VBLNK 
$VRSTR 

$VLPEN 

$NAME 

$VSTPM 

$SYNC 

$NOSYN 

$VTRAK 

$VRTLK 

$VUNLK 
$VSCRL 

$DFILE 
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The file modules in VTHDLR can be used in three different ways. When space 
is not critical, the most straightforward way is to link VTHDLR directly with 
a display program. The following command is an example. 

LINK PICTUR.yTHDLR 

It is often necessary to conserve space, however, and selective loading of 
modules is possible by first creating an indexed object module library from 
VTHDLR and then by making global calls within the display program. The 
following command creates an indexed object module library. 

LIBRARY/CREATE MTLIB VTHDLR 

To further conserve space with overlays, it is also possible to extract individ- 
ual object modules from a library and create separate object module files. For 
example, to link a display program using overlays, the following statements 
are a typical sequence of creating, extracting and linking commands. (NOTE: 
the modules VTCALl and VTCAL2 must be in the same overlay if any global 
in either one is used.) 



.LIBRARY/CREATE VTLIB MTHDLR 



.LIBRARY/EXTRACT VTLIB VTCALl 

GLOBAL? tVSTRT ! moves entire module with SVSTRT to VTCALl 

GLOBAL? ! Terminates promFtinS seauence 

.LIBRARY/EXTRACT VTLIB VTCAL2 

GLOBAL? *VBLNK ! Moves the entire module to VTCAL2 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTCAL3 

GLOBAL? *VLPEN ! Moves the entire module 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTCAL4 

GLOBAL? *VRTLK 'Moves the entire module 

GLOBAL? 

.LIBRARY/EXTRACT VTLIB VTBASE 

GLOBAL? SDFILE f Moves the entire module 
GLOBAL? 



.LINK/PROMPT PICTURf VTBASE 
KtVTCAL 1 f VTCAL2 r VTCAL3/0 { 1 
*VTCAL4/0:i 
*// 



A.5 Display File Structure 



The Display File Handler supports a variety of display file structures, takes 
over the job of display processor management for the programmer, and may 
be used for both assembly language graphics programming and for systems 
program development. For example, the Handler supports the tagged subpic- 
ture file structure used by the BASIC-11 graphics software, as well as simple 
file structures. These are discussed in this section. 
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A. 5.1 Subroutine Calls 

A subroutine call instruction, with the mnemonic DJSR, is implemented us- 
ing the display stop (DSTOP) instruction with an interrupt. The display stop 
interrupt routine in the Display File Handler simulates the DJSR instruction, 
and this allows great flexibility in choosing the characteristics of the DJSR 
instruction. 

The DJSR instruction stops the display processor and requests an interrupt. 
The DJSR instruction may be followed by two or more words, and in this 
implementation the exact number may be varied by the programmer at any 
time. The basic subroutine call has this form: 

DJSR 

Return Address 

Subroutine Address 

In practice, simple calls to subroutines could look Hke: 

DJSR 

.UORD .4-4 

.UORD SUB 

where SUB is the address of the subroutine. Control will return to the display 
instruction following the last word of the subroutine call. This structure per- 
mits a call to the subroutine to be easily by-passed without stopping the 
display processor, by replacing the DJSR with a display jump (DJMP) in- 
struction; 

njMP 

.WORD .+4 
. WORD SUB 

A more complex display file structure is possible if the return address is 
generalized: 

.DJSR 

♦WORD NEXT 

•WORD SUB 

where NEXT is the generalized return address. This is equivalent to the 
sequence: 

DJSR 

. WORD . +4 

.UORD SUB 

DJMP 

.WORD NEXT 

It is also possible to store non-graphic data such as tags and pointers in the 
subroutine call sequence, such as is done in the tagged subpicture display file 
structure of the BASIC-11 graphics software. This technique looks like: 

DJSR 

.WORD NEXT 



.WORD SUB 
DATA 



next: 



For simple applications where the flexibility of the DJSR instruction de- 
scribed above is not needed and the resultant overhead is not desired, the 
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Display File Handler (VTBASE.MAC and VTCALL.MAC) can be condition- 
ally re-assembled to produce a simple DJSR call. If NOTAG is defined during 
the assembly, the Handler will be configured to support this simple DJSR 
call: 



DJSR 
.WORD 



SUB 



where SUB is the address of the subroutine. Defining NOTAG will eliminate 
the subpicture tag capability, and with it the tracking object, which uses the 
tag feature to identify itself to the light pen interrupt handler. 

Whatever the DJSR format used, all subroutines and the user main file must 
be terminated with a subroutine return instruction. This is implemented as a 
display stop instruction (given the mnemonic DRET) with an argument of 
zero. A subroutine then has the form: 

SUBt Display Code 
DRET 
.WORD 



A.5.2 Main File/Subroutine Structure 

A common method of structuring display files is to have a main file which 
calls a series of display subroutines. Each subroutine will produce a picture 
element and may be called many times to build up a picture, producing 
economy of code. If the following macros are defined: 



.MACRO 


CALL <ARG> 


DJSR 




. WORD 


.+4 


. WORD 


ARG 


.ENDM 




.MACRO 


RETURN 


DRET 




.WORD 





.ENDM 





then a main file/subroutine file structure would look like: 
5 main display file 
main: 



Display Code 
CALL SUBl 
Display Code 
CALL SUB2 



SCALL SUBROUTINE 1 

fCALL SUBROUTINE 2 
5 ETC 



RETURN 
DISPLAY SUBROUTINES 

SUBi; Display Code 

RETURN 
i 
SUB2: Display Code 

RETURN 



{SUBROUTINE 1 

5 SUBROUTINE 2 
J ETC. 
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A. 5. 3 Basic-11 Graphic Software Subroutine Structure 

An example of another method of structuring display files is the tagged sub- 
picture structure used by BASIC-11 graphic software. The display file is 
divided into distinguishable elements called subpictures, each of which has its 
own unique tag. 

The subpicture is constructed as a subroutine call followed by the subroutine. 
It is essentially a merger of the main file/subroutine structure into an in-line 
sequence of calls and subroutines. As such, it facilitates the construction of 
display files in real time, one of the important advantages of BASIC-11 
graphic software. 

The following is an example of the subpicture structure. Each subpicture has 
a call to a subroutine with the return address set to be the address of the next 
subpicture. The subroutine called may either immediately follow the call, or 
may be a subroutine defined as part of a subpicture created earlier in the 
display file. This permits a subroutine to be used by several subpictures 
without duplication of code. Each subpicture has a tag to identify it, and it is 
this tag which is returned by the light pen interrupt routine. To facilitate 
finding subpictures in the display file, they are made into a linked hst by 
inserting a forward pointer to the next tag. 

SUBIJ DJSR J START OF SUBPICTURE 1 

.WORD SUB2 JNEXT SUBPICTURE 

.WORD SUEl+12 JJUMP TO THIS SUBPICTURE 

.WORD 1 JTAG = 1 

.WORD SUB2+6 fPOINTER TO NEXT TAG 

5 BODY OF SUBPICTURE 1 



DRET 


SUB2: DJSR 

.WORD SUB3 

.UORD SUB2+12 

.WORD 2 

.WORD SUB3+6 

JBODY OF SUBPICTURE 2 



J RETURN FROM 
5 SUBPICTURE 1 

f START SUBPICTURE 2 

JNEXT SUBPICTURE 

?JUMP TO THIS SUBPICTURE 

fTAG 2 

>PTR TO NEXT TAG 



BRET » RETURN FROM 

•WORD 5 SUBPICTURE 2 

SUB3: DJSR 5START SUBPICTURE 3 

.WORD SUB4 fNEXT SUBPICTURE 
.WORD SUBl + 12 ;COPY SUBPICTURE 1. 

»FOR THIS SUBPICTURE 
•WORD 3 ?BUT TAG IT 3. 

.WORD SUB4+6 JPTR TO NEXT TAG 

SUB4: DJSR ? START SUBPICTURE 4 

fETC. 
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A. 6 Summary of Graphics Macro Calls 









Assembly Language 






MACRO Call 


Expansion 


Mnemonic 


Function 


(see Note 1) 


(see Note 2) 


.BLANK 


Temporarily blanks 


.BLANK faddr 


.GLOBL $VBLNK 




a user display file. 




.IF NB, faddr 

MOV faddr, "100 

.ENDC 

JSR X'7, $VBLNK 


.CLEAR 


Initializes handler. 


.CLEAR 


.GLOBL $VINIT 
JSR '07, $VINIT 


.INSRT 


Inserts a call to 


.INSRT faddr 


.GLOBL $VNSRT 




user display file 
in handler's master 




.IF NB, faddr 
MOV faddr, 'OO 




display file. 




.ENDC 

JSR -07, $VNSRT 


.LNKRT 


Sets up vectors and 


.LNKRT 


.GLOBL $VRTLK 




links display file 




JSR "07, $VRTLK 




handler to RT-11 








scroller. 






.LPEN 


Sets up light pen 


.LPEN baddr 


.GLOBL $VLPEN 




status buffer. 




.IF NB, baddr 

MOV baddr, 'OO 

.ENDC 

JSR '07, SVLPEN 


.NAME 


Sets up buffer to 


.NAME \baddr 


.GLOBL $NAME 




receive name 




.IF NB, baddr 




register stack 




MOV .BEDDR, 'OO 




contents. 




.ENDC 

JSR '07, «NAME 


.NOSYN 


Disables power line 


.NOSYN 


.GLOBL $NOSYN 




synchronization. 




JSR '07, $NOSYN 


.REMOV 


Removes the call to 


.REMOV faddr 


.GLOBL $VRMOV 




a user display file. 




.IF NB, faddr 

MOV faddr, 'OO 

.ENDC 

JSR '07, $VRMOV 


.RESTR 


Unblanks the user 


.RESTR faddr 


.GLOBL $VRSTR 




display file. 




IF NB, faddr 

MOV faddr, "OO 

ENDC 

JSR "07, $VRSTR 


.SCROL 


Adjusts monitor 


.SCROL baddr 


.GLOBL $VSCRL 




scroller parameters. 




.IF NB, baddr 

MOV baddr, "OO 

.ENDC 

JSR "07, $VSCRL 
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Mnemonic Function 

.START Starts the display. 



MACRO Call 
(see Note 1) 

.START 



Assembly Language 

Expansion 

(see Note 2) 

.GLOBL $VSTRT 
JSR '07, SVSTRT 



.STAT 


Sets up status 


.STAT baddr 


.GLOBL $VSTPM 




buffer. 




.IF NB, baddr 

MOV baddr, "OO 

.ENDC 

JSR '07, $VS'1'PM 


.STOP 


Stops the display. 


.STOP 


.GLOBL $VSTOP 
JSR '07, $VSTOP 


.SYNC 


Enables power line 


.SYNC 


.GLOBL $SYNC 




synchronization. 




JSR '07, $SYNC 


.TRACK 


Enables the track 


.TRACK baddr, 


.GLOBL $VTRAK 




object. 


croutine 


IF NB, baddr 

MOV baddr, 'OO 

.ENDC 

.IF NB, croutine 

MOV croutine,- 

(-06) 

.IFF 

CLR-(-06) 

.ENDC 

.NARG T 

.IF EQ, T 

CLR 'OO 

.ENDC 

JSR '07, $VTRAK 


.UNLNK 


Unlinks display 


.UNLNK 


.GLOBL $VUNLK 




handler from RT-11 




JSR '07, SVUNLK 



if linked (otherwise 
leaves display stopped). 



NOTE 1 
baddr Address of data buffer, 

faddr Address of start of user display file, 

croutine Address of .TRACK completion routine. 

NOTE 2 

The lines preceded by a dot will not be assembled. 
The code they enclose may or may not be assembled 
depending on the conditionals. 
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A.7 Display Processor Mnemonics 



Mnemonic 


Value 


Function 


CHAR 


100000 


Character Mode 


SHORTY 


104000 


Short Vector Mode 


LONGV 


110000 


Long Vector Mode 


POINT 


114000 


Point Mode 


GRAPHX 


120000 


Graphplot X Mode 


GRAPHY 


124000 


Graphplot Y Mode 


RELATV 


130000 


Relative Point Mode 


INTO 


2000 


Intensity (Dim) 


INTl 


2200 


Intensity 1 


INT2 


2400 


Intensity 2 


INT3 


2600 


Intensity 3 


INT4 


3000 


Intensity 4 


INT5 


3200 


Intensity 5 


INT6 


3400 


Intensity 6 


INT7 


3600 


Intensity 7 (Bright) 


LPOFF 


100 


Light Pen Off 


LPON 


140 


Light Pen On 


BLKOFF 


20 


BHnk Off 


BLKON 


30 


Blink On 


LINED 


4 


Solid Line 


LINEl 


5 


Long Dash 


LINE2 


6 


Short Dash 


LINES 


7 


Dot Dash 


DJMP 


160000 


Display Jump 


DNOP 


164000 


Display No Operation 


STATSA 


170000 


Load Status A 
Instruction 


LPLITE 


200 


Light Pen Hit On 


LPDARK 


300 


Light Pen Hit Off 


ITALO 


40 


Italics Off 


ITALl 


60 


Italics On 


SYNC 


4 


Halt and Resume 
Synchronized 


STATSB 


174000 


Load Status B 
Instruction 



INCR 



100 



Graphplot Increment 



Vector/Point Mode 
INTX 

MAXX 
MAXY 

MINUSX 

MINUSY 



40000 



1377 

20000 
20000 



Intensity Vector or 
Point 

Maximum Y Component 

Negative X Component 
Negative Y Component 
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Mnemonic 




Value 


Short Vector Mode 




SHIFTX 


= 


200 


MAXSX 


= 


17600 


MAXSY 


= 


77 


MISVX 


=^ 


20000 


MISVY 


= 


100 



Function 



Maximum X Component 
Maximum Y Component 

Negative X Component 
Negative Y Component 



A. 8 Assembly Instructions 

A.8.1 General Instructions 

All programs can be assembled in 16K, using RT-11 MACRO. All assemblies 
and all links should be error free. The following conventions are assumed: 

1. Default file types are not explicitly typed. These are .MAC for source files, 
.OBJ for assembler output, and .SAV for Linker output. 

2. The default device (DK) is used for all files in the example command 
strings. 

3. Listings and link maps are not generated in the example command 
strings. 



A.8.2 VTBASE 

To assemble VTBASE with RT-11 link-up capability. 

MACRO MTBASE 

A.8.3 VTCAL1 - VTCAL4 

To assemble the modules VTCALl through VTCAL4; 

MACRO VTCALl TVTCAL2»yTCAL3»VTCAL4 

A.8.4 VTHDLR 

To create the concatenated handler module: 

COPY/BINARY VTCALl .OBJ .yTCAL2* OBJ, VTCAL3, OBJ,- 
VTCAL4 . OBJ T VTBASE . OBJ VTHDLR . OBJ 

A.8.5 Building VTLIB.OBJ 

To build the VTLIB library: 

LIBRARY/CREATE VTLIB VTHDLR 
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A.9 VTMAC 



.TITLE VTMAC 
i THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY ONLY BE USED 
i OR COPIED IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE. 

i COPYRIGHT <C) 1978» DIGITAL EQUIPMENT CORPORATION. 

i VTMAC IS A LIBRARY OF MACRO CALLS AND MNEMONIC DEFINITIIONS WHICH 
( PROVIDE SUPPORT OF THE VTll DISPLAY PROCESSOR. THE MACROS PRODUCE 
t CALLS TO THE VTll DEVICE SUPPORT PACKAGEr USING GLOBAL REFERENCES. 

J MACRO TO GENERATE A MACRO WITH ZERO ARGUMENTS. 
.MACRO MACO NAME » CALL 

.MACRO NAME 

.GLOBL CALL 
JSR PC»CALL 

. ENDM 
. ENDM 

i MACRO TO GENERATE A MACRO WITH ONE ARGUMENT 

.MACRO MACl NAMEjCALL 

.MACRO NAME ARG 

.IF NBfARG 

MOV ARGf%"00 

.ENDC 

.GLOBL CALL 

JSR PC » CALL 

.ENDM 
.ENDM 

} MACRO TO GENERATE A MACRO WITH TWO OPTIONAL ARGUMENTS 

.MACRO MAC2 NAME » CALL 

.MACRO NAME ARG1»ARG2 
.GLOBL CALL 
.IF NB»ARG1 



MOV ARGl»/i"00 

.ENDC 

♦IF NBjARG2 

MOV ARG2»-CSP) 

.IFF 

CLR -(SP) 

.NARG T 

.IF EQ»T 

CLR yroo 

.ENDC 

.ENDC 

JSR PC J CALL 

.ENDM 



.ENDM 



J MACRO LIBRARY FOR VTll) 



MACO 
MACO 
MACO 
MACl 
MACl 
MACl 
MACl 
MACl 
MACl 



<. CLEAR 
<.STOP 
<. START 
<.IN3RT 
<,REMOV 
<. BLANK 
<.RESTR 
<. STATE- 
'S:. LPEN> 



>,<*vinit;:: 

»<*VSTOP> 

>»<*vstrt::^ 

*VNSRT> 

*VRMOV:: 

>f<*VBLNKJ 

>,<*vrstr:; 

t <*VSTPM> 
»<*VLPEN> 
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HACl <.SCROL>»<*VSCRL> 

MAC2 <,TRACK>»<*VTRAK> 

MACO < . LNKRT> » <*yRTLK> 

MACO < . UNLNK> , <*yUNLK> 

» MNEMONIC DEFINITIONS FOR THE VTll DISPLAY PROCESSOR 



DJMP= 


160000 


DNOP= 


164000 


DJSR= 


173400 


DRET= 


173400 


DNAME 


=173520 


DSTAT 


=173420 


DHALT 


=173500 



? DISPLAY JUMP 

? DISPLAY NOP 

J DISPLAY SUBROUTINE CALL 

? DISPLAY SUBROUTINE RETURN 

5SET NAME REGISTER 

; RETURN STATUS DATA 

J STOP DISPLAY AND RETURN STATUS DATA 



CHAR=100000 

SH0RTV=104000 

LONGV=HOOOO 

P0INT=114OOO 

GRAPHX= 120000 

GRAPHY=124000 

RELATV=130000 



f CHARACTER MODE 

J SHORT VECTOR MODE 

SLONG VECTOR MODE 

r POINT MODE 

5 GRAPH X MODE 

r GRAPH Y MODE 

fRELATIVE VECTOR MODE 



INTO= 
INT1 = 
INT2= 
INT3= 
INT4= 
INT5= 
INT6= 
INT7= 



:2000 
2200 
^2400 
2600 
3000 
3200 
3400 
3600 



^INTENSITY 



LP0FF=100 

LP0N=140 

BLK0FF=20 

BLK0N=30 

LINE0=4 

LINE1=5 

LINE2=6 

LINE3=7 



SLIGHT PEN OFF 
SLIGHT PEN ON 
rBLINK OFF 
fBLINK ON 
5 SOLID LINE 
;L0NG DASH 
f SHORT DASH 
5 DOT DASH 



STATSA=170000 

LPLITE=200 

LPDARK=300 

ITAL0=40 

ITAL1=60 

SYNC=4 



JLOAD STATUS REG A 

f INTENSIFY ON LPEN HIT 

fDON'T INTENSIFY 

} ITALICS OFF 

r ITALICS ON 

JPOUER LINE SYNC 



STATSB=174000 

INCR=100 

INTX=40000 

MAXX=1777 

MAXY=1377 

MINUSX=20000 

MINUSY=20000 

MAXSX=17600 

MAXSY=77 

MISVX=20000 

MISyY=100 



rLOAD STATUS REG B 
JGRAPH PLOT INCREMENT 
» INTENSIFY VECTOR OR POINT 
SMAXIMUM X INCR. = LONGV 
rMAXIMUM Y INCR. = LONGV 
^NEGATIVE X INCREMENT 
^NEGATIVE Y INCREMENT 
^MAXIMUM X INCR. = SHORTV 
f MAXIMUM Y INCR. = SHORTV 
^NEGATIVE X INCR. = SHORTV 
^NEGATIVE Y INCR. = SHORTV 
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Appendix B 

System Macro Library 



This appendix contains the listing of the system macro library (SYS- 
MAC.SML) for Version 4 of RT-11. This library is stored on the system 
device. It is used by MACRO when expanding the programmed requests and 
calling the subroutines that are described in Chapter 2. 



SYSMAC.MAC - SYSTEM MACRO LIBRARY 
RT-11 V04.00 

COPYRIGHT (c) 1979j 1980 BY 
DIGITAL EQUIPMENT CORPORATION* MAYNARD. MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT, TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 



.MACRO ..VI.. 

.MCALL ...CM0»...CMl»...CM2»...CM3j...CM4T...CM5f...CM6 

...Vl=l 
.ENDM 

.MACRO ..V2.. 

.MCALL . . .CMOr . . .CM1» . . .CM2» . . .CM3f . . .CM4r . . .CM5f . . .CM6 

. . .Vl=2. 

.ENDM 

.MACRO .MACS 

.MCALL ...CMC. .CMl.. ..CM2! ...CM3.. ..CM4f ...CM5,.. .CM6 

...Vl=3. 
.ENDM 

.MACRO . . .CMO STARG 
.IF B <STAR6> 

CLR -(6.) 
.IFF 
.IF IDN <STARG>»*0 

CLR -(6.) 
» IFF 

MOV STARBf-<6.) 
.ENDC 
.ENDC 
.ENDM 
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.MACRO ...CMl AREftflCCHANfFLAG 

...CHS <AREA> 

. ..V2=0 

.IF B <FLAG> 

.IIF B <AREA>j ,..V2=1 

.IFF 

.IIF DIF <FLAG>,SET, ...V2=l 

.ENDC 

.IF NE ...V2 

.IF IDN <CHAN>F<*0> 

CLRB (0) 
.IFF 
.IF NB <CHAN> 

MOVB CHAN.(O) 
.ENDC 
.ENDC 
.IFF 
.IF B <CHAN> 

MOVB *ICfl(0) 
.IFF 

.NTYPE ...V2»CHAN 
.IF EQ . . .V2-"027 

MOM CHAN+<IC*"0400>f (0) 
.IFF 

MOV ♦IC*"0400.(0) 

MOVB CHAN,(0) 
.ENDC 
.ENDC 
.ENDC 
.ENDM 

.MACRO ...CM2 ARG.OFFSEflNSrCSETfBB 
.IF B <ARG> 
.IF NB <CSET> 
.IF NE ...Vl-3. 

CLR'BB OFFSE(O) 
.ENDC 

.ENDC 

.IFF 

.IF IDN <ARG>j»0 

CLR'BB OFFSE(O) 
.IFF 

MOV'BB AR6»0FFSE(0) 
.ENDC 
.ENDC 
.IF NB <INS> 

EMT "0375 
.ENDC 
.ENDM 

.MACRO ...CM3 CHAN.IC 
.IF B <CHAN> 

MOV #IC«'*0400»Z0 
.IFF 

.NTYPE ..,V2,CHAN 
.IF EQ ...V2--027 

MOV CHAN+<IC*"0400>»%0 

.IFF 

MOV *IC«"0400»X0 
BISB CHANrZO 



.ENDC 

.ENDC 

.ENDM 



EMT "0374 



.MACRO ...CM4 AREA. CHAN, BUF,UCNT,BLKrCRTN.IC»CODE 

. . .CMl <AREA>.<IC>r<CHAN>.<CODE> 

...CM2 <BLK>.2. 

...CM2 <BUF>»4. 

. ..CM2 <WCNT>f6. 
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...CM2 <CRTN>i8.fX 
.ENDK 

.HACRO ...CMS SRC»BB 

•IF NB <SRC> 

.IF DIF <SRC>fRO 

HOM'BB SRCr%0 
.ENDC 
.ENDC 
,ENDH 

♦MACRO ...CMA AREAflCjCHANfFLAG 
...CMS <AREA> 
.IF B <FLAG> 
.IF NB <aREa> 

MOV #IC«"0400+CHANf <0> 

.ENDC 

.IFF 

•IF IDN <FLA6>»SET 

MOV »IC*"0400+CHANir<0) 
.ENDC 
.ENDC 
.ENDM 

.MACRO .CDFN AREAfADDR. NUM. CODE 

•IF NDF ,..V1 

.MCALL .MACS 

.MACS 

.ENDC 

,..CM6 <AREA>.13.»0.<CQnE> 

...CM2 <ADDR>»2. 

...CM2 <NUM>.4,.X 

.ENDM 

.MACRO .CHAIN 

MOV »B,«"0400»%0 

EMT "0374 
.ENDM 

.MACRO .CHCOP AREA»CHAN,OCHAN,JOBBLK»CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

,,,CM1 <AREA>.ll..<CHAN>f<CODE> 

...CM2 <0CHAN>.2. 

.IF NB <J0BBLK> 

...CM2 <J0BBLK>f4..X 

.IFF 

..,CM2 «0>4.»X 

.ENDC J MB <JOBBLK> 

.ENDM 

.MACRO .CLOSE CHAN 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ ...Vl-1 

EMT "0<160+CHAN> 
.IFF 

, . ,CM3 <CHAN>.6. 
.ENDC 
.ENDM 

.MACRO .CNTXS AREA* ADDR* CODE 

.IF NDF . ..VI 

.MCALL .MACS 

.MACS 

.ENDC 
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...CM6 <AREA>r27..0i<C0DE> 

...CM2 <ADDR>,2,.X 

.ENDM 

.MACRO .CMKT AREA» ID, TIME»CODE 

.IF NDF , . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>>19. ,0><COIiE> 

. . .CM2 <iri>»2. 

...CM2 <TIME>r4.,X,X 

.ENDM 

.MACRO .CRAW AREA, ADDR, CODE 

.IF NDF .. .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>,30. j2. ,<CODE> 

...CM2 <ADDR>r2.,X 

.ENDM 

.MACRO .CRR6 AREA, ADDRr CODE 

.IF NDF ,..V1 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>j30. ,Oj<CODE> 

...CM2 <ADDR>,2.,X 

.ENDM 

.MACRO .CSIGE DEVSPCDEFEXT^CSTRNG , LINBUF 

.IF NDF ...yi 

.MCALL .MACS 

.MACS 

.ENDC 

.IF NB <LINBUF> 

...CMO <LINBUF> 

.NTYPE ...V2»DEVSPC 

.IF EQ ...V2-"027 

...CMO <DEVSPC'+1> 

.IFF 

...CMO <DEVSPC> 

INC <6.) 
,ENDC 
.IFF 

...CMO <DEVSPC> 
.ENDC 

...CMO <DEFEXT> 
...CMO <CSTRNG> 

EMT "0344 
.ENDM 

.MACRO .CSISP OUTSPCrDEFEXTfCSTRNCLINBUF 

.IF NDF ...yi 

.MCALL .MACS 

.MACS 

.ENDC 

.IF NB <LINBUF> 

...CMO <LINBUF> 

.NTYPE ...V2,0UTSPC 

.IF EQ , . .V2-"D27 

...CMO <0UTSPC'+1> 

.IFF 

...CMO <OUTSPC> 

INC (6.) 
.ENDC 
.IFF 
...CMO <OUTSPC> 
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.ENDC 

...CMO <DEFEXT> 

,>>CHQ <CSTRNG> 

EMT "0345 
,ENDH 

.HACRO .CSTAT AREA.CHANf ADDRfCODE 

,IF NDF ...yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CMl <AREA>f23.f<CHAN>.<C0DE> 

,,.CM2 <ADDR>»2.jX 

.ENDM 



.MACRO .CTIMI 
JSR 
.UORD 
.UORD 



.ENDM 
.MACRO 

.ENDM 



.DATE 
MOV 
EMT 



TBK 

%5re»TIMIT 

TBK-. 

1 



»10,«"0400.%0 
"0374 



•MACRO .DELET 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ ...Vl-1 

...CMS <CHAN> 

EMT "0<AREA> 
. IFF 

...CMS <AREA> 
.IF IDN <CHAN>»#0 

CLR (0) 
.IFF 
.,.V2=0 
.IF B <CODE> 
.IIF B <AREA>T ., .V2=l 
.IFF 

.IIF DIF <CODE>»SETf ...V2=l 
.ENDC 

.IF NE .. .V2 
.IF NB <CHAN> 

MOVB 
.ENDC 
.IFF 
,IF B <CHAN> 

CLRB 
.IFF 
.NTYPE 
.IF EQ ...V2 

MOV 



AREA? CHAN fDBLKsSEQNUMs CODE 



CHANt(O) 



1(0) 



.,.V2jCHAN 

027 

CHANr (0) 



.IFF 



CLR (0) 
MOVB CHAN.(O) 

.ENDC 

.ENDC 

.ENDC 

.FNDC 

...CM2 <DBLK>.2. 

...CM2 <SEClNUM>.4.fX>X 

. ENDC 

.ENDM 



•MACRO .DEVIC 
.IF NDF . . .VI 



AREA.ADDRfLINKiCODE 
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.MCALL .MACS 

.MACS 

.ENDC 

.IF B LINK 

...CM6 <AREA>»12. »0»<COIiE> 

.IFF 

...CM6 <AREA>f 12. »lr<CODE> 

. ENDC 

...CM2 <ADDR>»2.,X 

.ENDM 



.MACRO .riRAST NAMEfPRI.ABT 
.GLOBL *INPTR 
.IF B <ABT> 

RTS X7 
.IFF 

BR ABT 
.ENDC 
NAME'INTJ! JSR ZSjSSINPTR 

.WORD "C<PRI«"040>S"0340 
.ENDM 



.MACRO .DRBE6 
.ASECT 



NAME>VEC»DSIZ.DSTSfVTBL 



.GLOBL NAME'END»NAME'INT 

.WORD <NAME' END-NAME 'STRT> 



.IF B 


<DSIZ> 






.WORD 


NAME'DSIZE 


.IFF 








.UORD 


DSIZ 


• ENDC 






.IF B 


<DSTS> 






.WORD 


NAME'STS 


.IFF 








.WORD 


DSTS 


.ENDC 








.WORD 


ERL«G+<MMG»T«2>+<TIM«IT«4> 


. = 176 






•IIF DF 


NAME'*CSR. .WORD NAME'SCSR 



<VTBL-.>/2. -1 + "0100000 

.ERROR VEC ;ODD OR ILLEGAL VECTOR SPECIFIED 
yECt-C3 



.PSECT NAME'DMR 
NAME'STRTJ t 
.IF NB UTBL 
•GLOBL VTBL 

.WORD 
.IFF 

.IF NB <VEC> 
.IIF ME VECJ3 

.WORD 
.IFF 

•IF DF NAME'»VTB 
.GLOBL NAME'$VTB 

.WORD <NAME'«VTB-.>/2. -1 + "0100000 
.IFF 
.IIF NE NAHE'»VEC13 .ERROR NAME'$VEC >ODD OR ILLEGAL VECTOR SPECIFIED 

.WORD NA«E'»VEC8"C3 
.ENDC 
.ENDC 
.ENDC 

.WORD 
NAME'SYSS: 
NANE'LGiEtS 
NAHE'CQEJ: 
.ENDM 



NAME'INT-.>"0340 



.WORD 
.WORD 



.MACRO .DRBOT NAME.ENTRYjREAD 

.DRENO NAME 
.IIF NDF TPS» TPS=1775A4 
.IIF NDF TPB. TPB=177566 

LF=12 
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CR=15 

B$B00T=1000 

B*nEVN=4716 

B*riEyU=4722 

B$READ=4730 

,IF EG HHG«T 

B*DNAM="R'NAME 

► IFF 

E$DNAM="R'NAME'X 

.ENDC 

•ASECT 

.=62 

. WORD NAHE ' BOOT f NAME ' BEND-NAME ' BOOT f READ-NAME ' BOOT 
•PSECT NAHE'BOOT 
NAME 'BOOT:: NOP 

BR ENTRY 
.ENDM 

.MACRO .DRDEF NAMEt CODE ,STATf SIZEiCSR. VEC 

.MCALL .DRAST. .DRBEGf .DRBOTi .DREND» .DRFIN, .DRSET» .DRUTB» .FORK» .QELDF 

.IIF NDF TIM»ITf TIM1IT=0 

.IIF NE TIM$IT» TIM«IT=1 

.IIF NDF MM6»T> MMG$T=0 

,IIF NE MMe»T. MMG*T=1 

.IIF NDF ERL$Q. ERL»G=0 

.IIF NE ERLtG» ERL«G=1 

.IIF NE TIM»IT> .MCALL .TIHIu» .CTIMI 

.QELDF 

HnERR*=l 

EOF«=20000 

SPFUN«=2000 

HNDLR»=4000 

SPECL«=10000 

U0NLY«=20000 

R0NLY«=400OO 

FILST«=100000 

NAME'DSIZ=SIZE 

NAME'$COD=CODE 

NAME'STS-<CODE> l<STAT> 

.IIF NDF NAME'»CSR» NAME'»CSR-CSR 

.IIF NDF NAME'$VECf NAME'«VEC=VEC 

.GLOBL NAME '♦CSRf NAME '$VEC 

.ENDM 



'«end: 



.MACRO .DREND 


NAME 


.PSECT NAME'DVR 


.IIF NDF NAME'»END. NAME 


.IF EQ .-NAME' 


«END 


name'$emdj: 




.IF NE MMG$T 




♦RLPTRJS .WORD 





iMPPTR:; .WORD 





*gtbyt;5 .uord 





♦ptbyt:: .word 





$PTMRD!J .WORD 





.ENDC 




.IF NE ERLiG 




$ELPTR5: .WORD 





.ENDC 




.IF NE TIMilT 




*timit:: .word 





.ENDC 




*inptr:s .word 





tFKPTRIt .WORD 





.GLOBL NAHE'STRT 


NAME'END == . 




.IFF 




.PSECT NAME 'BOOT 



.IIF LT <NAME'B00T-.+664>» .ERROR fPRIMARY BOOT TOO LARGE 
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= NAME'B00T+6A4 

bioerr: jsr ri. report 

•WORD IOERR-NAME'BOOT 



report: 


Moy 


♦BOOTF-NAME'BOOT.RO 




JSR 


RlrREP 




MOV 


(R1)+»R0 




JSR 


RlrREP 




MOV 


*CRLFLF-NAME'BOOT»RO 




JSR 


Rl.REP 




RESET 






HALT 






BR 


.-2 


REPOR! 


MOVB 


<RO)+fe*TPB 


REPS 


TSTB 


e#TPS 




BPL 


REP 




TSTB 


SRO 




BNE 


REPOR 




RTS 


Rl 



bootf! .asciz <cr><lf>"?b00t-u-'<200> 
crlflf: .asciz <cr><lf><lf> 

IOERR: .asciz "I/O error* 
.EVEN 

name'bend:: 

.ENDC 
.ENDM 

.MACRO .DRFIN NAME 
.GLOBL NAME'CQE 

MOV X7.Z4 

ADD *NAME'CQE-.fZ4 

MOV e»"054TX5 

JMP e''0270<5) 



OPTION, MAL»RTN»MODE 



.ENDM 

.MACRO .DRSET 

.ASECT 

.IF LT .-400 

.=400 

.IFF 

. = .-2 

.ENDC 

VAL 
...V2=. 

.RAD50 \OPTXON\ 
.=. . .V2+4 

.BYTE <RTN-400>/2 
...V2=0 
•IRP Xf<MODE> 
.IF IDN <X>r<NUM> 
.. .V2=...V2!100 
.IFF 

.IF IDN <X>F<NO> 
. . .V2=. . .V2I200 
.IFF 

.IF IDN <:X>t<OCT> 
...V2=...V2!140 
.IFF 

.ERROR JILLEGAL PARAMETER X 
.ENDC 
.ENDC 
.ENDC 
.ENOR 



.BYTE 
.WORD 
.ENDM 

.MACRO .DRVTB 



. ..V2 




NAMEfVEC.INT.PS=0 
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.IF NB 


NAME 




WAHE'fVTBJ: 




.IFF 






. = .-2 






.ENDC 








.WORD 


yECS"C3,INT- 


.ENDM 






.MACRO 


.DSTAT 


RETSPCjDNAM 


.IF NDF 


.. .VI 




.MCALL 


.MACS 




.MACS 






.ENDC 






. . . PMS 


<riNiM> 




i.'icMO 


<RETSPC 


> 




EMT 


"0342 


.ENDM 






.MACRO 


.ELAU 


AREAfADDRfCO: 


.IF NDF 


. ..VI 




.MCALL 


.MACS 




.MACS 






.ENDC 






.. .CM<& 


<AREA>. 


30. .3. f<CODE> 


..,Cri2 


<ADDR>» 


2..X 


.ENDH 







.MACRO .ELR6 AREA* AODRrCODE 

.IF NDF ...VI 

.HCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>»30.fl»<C0DE> 

...CH2 <AD0R>r2.rX 

.ENDM 

.MACRO .ENTER AREA>CKAN>DBLKrLENf SEQNUMpCODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ ...Vl-1 

...CM5 <CHAN> 

...CMO <DBLK> 

EMT "0<40+AREA> 
.IFF 

...CMl <AREA>f2. t<CHAN>.<COnE> 
...CM2 <DBLK>»2. 
...CM2 <LEN>f4.ffX 
.,.CM2 <SEQNUM>.6..XfX 
.ENDC 
• ENDM 

.MACRO .EXIT 

EMT "0350 
.ENDM 

.MACRO .FETCH ADDRfDNAM 

.IF NDF ...Vl 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <DNAM> 

...CMO <ADDR> 

EMT "0343 
.ENDM 

.MACRO .FORK FKBLK 

JSR Z5fB*FKPTR 
.WORD FKBLK - . 
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.ENDM 

.MACRO ,6MCX AREA» ADDRfCODE 

.IF NDF ...Ul 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>f30..6.f<C0DE> 

...CM2 <ADDR>>2.>X 

.ENOM 

.MACRO .GTIM AREA» ADDRiCODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>»17.f0»<C0DE> 

...CM2 <ADDR>F2.fX 

.ENOM 

.MACRO .GTJB AREA» ADDR. JOBBLKtCODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>rl6.rl><C0DE> 

...CM2 <ADDR>f2. 

.IF NB <JOBBLK> 

•IF IDN <JOBBLK>»<ME> 

...CM2 *-l»4.fX 

.IFF 

...CM2 <J0BBLK>i4.»X 

.ENDC 5IDN <J0BBLK>f<ME> 

.IFF 

...CM2 #-3.4. »X 

.ENDC fNB <JOBBLK> 

.ENDM 

.MACRO .GTLIN LINBUF. PROMPT 

.IF NDF ...Vl 

•MCALL .MACS 

.MACS 

.ENDC 

...CMO <LINBUF> 

...CMO *1 

...CMO <PROMPT> 

CLR -(6.) 

EMT "0345 
.ENDM 

.MACRO .GVAL AREA»OFFSEf CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>>28.r0.<C0DE> 

...CM2 <0FFSE>,2.»X 

.ENDM 

.MACRO .HERR 

MOV *5.«"0400.ZO 



EMT "0374 



.ENDM 



.MACRO .HRESE 

EHT "0357 
.ENDM 

.MACRO .INTEN PRIO>PIC 
.IF B PIC 
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JSR 


5.»e"054 


.IFF 








MOV 


e*"054,-(6.) 




JSR 


5.»(?(6.) + 


.ENDC 








.WORD 


"C<PRI0*32.> 


.ENDM 






.MACRO 


.LOCK 






EMT 


"0346 


.ENDM 






.MACRO 


.LOOKU 


AREA T CHAN »DB 


.IF NDF 


.. .VI 




.MCALL 


.MACS 




.MACS 






.ENDC 






.IF EQ 


. .,V1-1 




...CMS 


<CHAN> 






EMT 


"0<20+AREA> 



.irEMl <AREA>fl»<CHAN>.<CODE> 

...CM2 <DBLK>t2. 

,..CM2 <SEQNUM>.4.fXiX 

• ENDC 

.ENDM 

.MACRO .MAP AREA>ADDR>CODE 

.IF NDF . ..VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>r30.»4,»<C0DE> 

...CM2 <ADDR>.2.>X 

.ENDM 

.MACRO .MTATC AREA. ADDR lUNIT. CODE 

.IF NDF , ..VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>t31. .5. »<CODE> 

...CM2 <ADDR>»2, 

,.,CM2 ::UNIT>j4. »X. .B 

.ENDM 

.MACRO .MTDTC AREA? UNIT. CODE 

.IF NDF .. ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

. . ,CM6 <AREA'>t31. .6, .<CODE> 

...CM2 <UNIT>.4,rX 

.ENDM 

.MACRO .MTPRN AREA. ADDR. UNIT. CODE 

.IF NDF .. .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 AREA.31. ,7. .<CODE> 

...CM2 ADDR.2. 

...CM2 <UNIT>.4. .X. .B 

.ENDM 

.MACRO .MFPS ADDR 

MOv @#"054j-(6.) 

ADD «"0362.(6.) 

JSR 7..B(6.)+ 

•IIF NB <ADDR> MOVB <6.)+.ADDR 

.ENDM 
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.MACRO .MTRCT AREA, UNIT j CODE 

.IF NDF ...gi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>i31. »4. ,<CODE> 

...C«2 <UNIT>.4.,X 

.ENDM 

.MACRO .MRKT AREAr TIME, CRTN, ID, CODE 

.IF NDF .. .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>»18. ,0,<CODE> 

...CM2 <TIME>,2. 

...CM2 <CRTN>,4. 

.,.CM2 <ID>,6.rX 

.ENDM 

.MACRO .MTGET AREA, ADDR, UNIT, CODE 

.IF NDF ,,.V1 

.MCALL .MACS 

.MACS 

.ENDC 

...CM^ AREA,31.,1,<C0DE> 

...CM2 ADDRf2. 

,..CM2 <UNIT>,4.,X,,B 

.ENOH 

.MACRO .MTPS ADDR 

.IIF NB <ADDR> CLR -(6.) 

.IIF NB <ADDR> MOVB ADDR,<6.) 

MOV e*"054,-(6.) 

ADD #"0360, (6.) 

JSR 7. ,9(6.)+ 
.ENDM 

.MACRO .HTSET AREA, ADDR, UNIT, CODE 

.IF NDF ,.,yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 AREA,31.,0,<C0DE> 

...CH2 ADDR, 2. 

...CM2 <UNIT>,4.,X,,B 

.ENDM 

.MACRO .MTIN AREA, ADDR, UNIT, CHRCNT , CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 AREA»31.,2. ,<CODE> 

..,CM2 ADDR, 2. 

...CM2 <UNIT>,4.,,,B 

...CM2 <CHRCNT>,5.,X,,B 

.ENDM 

.MACRO .MTOUT AREA, ADDR, UNIT, CHRCNT , CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 AREA,31. ,3.,<C0DE> 

...CM2 ADDR, 2. 

...CM2 <UNIT>,4.,,,B 

...CM2 <CHRCNT>,5.,X,,B 

.ENDM 
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.MACRO .MTSTA AREA» ADDRfCODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 AREA»31.>8.r<C0DE> 

...CM2 A0DRf2. 

...CM2 »0f4.»X 

.ENDH 

.MACRO .HUAIT 

MOV #9.«-0400.XO 

EMT "0374 
.ENDM 

.MACRO .PRINT ADDR 
.IF NB <ADDR> 
.IF DIF <ADDR>fRO 

MOV ADDRfZO 
.ENDC 
.ENDC 

EMT "0351 
.ENDM 

.MACRO .PROTE AREA» ADHRfCODE 
.IF NDF , ,.U1 
.MCALL .MACS 



.MACS 




.ENDC 




...CM6 


<AREA>,25..0.<C0DE5 


. ..CM2 


<ADDR>.2. .X 


.ENDM 




.MACRO 


.PURBE CHAN 


.IF NDF 


. . .VI 


.MCALL 


.MACS 


.MACS 




.ENDC 




...CM3 


<CHAN>,3. 


.ENDM 





.MACRO .QELDF 

Q.LINK=0 

Q.CSW=2. 

Q.BLKN=4. 

H.FUNC=6. 

Q.JNUM=7. 

Q.UNIT=7. 

Q.BUFF = ''010 

Q.WCNT="012 

C1.C0MP="014 

.IRP X» <LINK»CSy»BLKNrFUNCi JNUMtUNITj BuFFfWCNT.COMF, 

Q$'X = CI. 'X-4 

.ENDR 

.IF EQ MMG$T 

Q.ELGH="016 

.IFF 

Q.PAR="016 

Q$PAR="012 

Q.ELDH = ''024 

ENDC 

ENDM 

MACRO .QSET ADDRfLEN 

IF NDF . ..VI 

MCALL :MACS 

MACS 

ENDC 

..CM5 <LEN> 

..CMO <ADDR> 
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EMT "0353 
.ENOM 

.MACRO .RCTRL 

EMT "0355 
.ENDM 

.MACRO .RCVD AREA, BUF. WCNT»CRTN=#1 , CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENBC 

.IIF IDN <CODE>»NOSET» ...CM4 <AREA>. ,<BUF> r <UCNT>r ,<CRTN>. 22. . <CODE> 

.IIF DIF <CODE>»NOSETr ...CM4 <AREA>,*0 . <BUF> j <UCNT>. ,<CRTN> »22. . <CDDE; 

.ENDM 

.MACRO .RCVDC AREA, BUF,WCNT»CRTN. CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IIF IDN <CODE>jNOSETt ..,CM4 <AREA>f ,<BUF>.<UCNT> , r <CRTN> » 22 . ,<CODE> 

.IIF DIF <CODE>,NOSETj . . .CM4 <AREA> » tO»<BUF>5 <UCNT>, , <CRTN> r 22 . ,<C0DE> 

.ENDM 

.MACRO .RCVDU AREA, BUFr WCNT.CRTN=#0»C0DE 

.IF NDF . ,.V1 

.MCALL .MACS 

.MACS 

.ENDC 

.IIF IDN <CODE>,NOSET, ...CM4 <AREA>, ,<BUF>»<UCNT> , , <CRTN> ,22 . , <CODE> 

•IIF DIF <CODE>,NOSET, ..,CM4 <AREA>, *0,<BUF>,<WCNT> , , <CRTN>r 22 . , f CODF ; 

.ENDM 

.MACRO .RDEBK RGSI2 
.MCALL .RDBDF 
.RDBDF 

.WORD 

.WORD RGSIZ 

.WORD 
.ENDM 

.MACRO .RDBDF 

R.6ID =0 

R.GSIZ =2. 

R.GSTS =4. 

R.GLGH =6. 

RS.CRR ="0100000 

RS.UNM ="040000 

RS.NAL ="020000 
.ENDM 

.MACRO .READ AREA, CHAN, BUF, WCNT , BLKfCRTN=*l , CODE 

.IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EG) ...Vl-1 

...CM5 <UCNT> 

...CMO #1 

...CMO <BUF> 

...CMC <CHAN> 

EMT "0<200+AREA> 
.IFF 

. . .CM4 <AREA>,<CHAN>,<BUF>,<WCNT>,<BLK>,<CRTN>,8. , <CODE> 

.ENDC 

.ENDM 

.MACRO .READC AREA, CHAN , BUF , UCNT , CRTN, ELK, CODE 
.IF NDF ...VI 
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.MCALL .MACS 

.MACS 

.ENDC 

.IF EO ...Ml-1 

..,CM5 <crtn:> 

...CMO <WCNT> 
...CMO <BUF> 
...CMO <CHAN> 

EMT "0<200+AREA> 
.IFF 

. . . CM4 <AREA> » <CHAN>f <BUF> f <UCNT> , <BLK> > <CRTN> » 8 . » <COriE> 
.ENDC 
.ENDM 

.MACRO .READU AREA> CHAN> BUF.UCNT > BLK> CRTN=40 > CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .yi-1 

...CMS <WCNT> 

. ..CMO 

...CMO <BUF> 

...CMO <CHAN> 

EMT "0<200+AREA> 
.IFF 

. . . CM4 <AREA> f <CHAN>> <BUF> » <WCNT> » <BLK> > <CRTN> ,8, , <CO0E> 
.ENDC 
.ENDM 

.MACRO .REGDEF 
.ENDM 

.MACRO .RELEA DNAM 

.IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <DNAM> 

. , .CMO 

EMT "0343 
.ENDM 

.MACRO .RENAM AREAjCHAN. DBLK.CODE 

.IF NDF . . .vi 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .yi-1 

...CMS <CHAN> 

EMT "0<100+AREft> 
.IFF 

. . . CMl <AREA> . 4 . . <CHAN> i <CODE> 
...CM2 <DBLK>>2.fX 
.ENDC 
.ENDM 

.MACRO .REOPE AREA» CHAN. CBLK» CODE 

.IF NDF . . ,V1 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .Vl-1 

...CMS <CHAN> 

EMT "0<140+AREA> 
.IFF 

. . .CMl <AREA>.6. .<CHAN>.<CODE> 
...CM2 <CBLK>»2..X 
.ENDC 
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.ENDM 

MACRO .SAVES AREA.CHANr CBLK. CODE 

IF NDF ...VI 

MCALL .MACS 

MACS 

ENDC 

IF EO .. .Vl-1 

..CM5 <CHAN> 

EMT '•0<i20+AREA> 
IFF 

. .CMl <AREA>j5. j<CHAN>><COnE> 
.,CM2 <CBLK>.2.»X 
ENDC 
ENDM 

.MACRO .RSUM 

MOV *2.*"0400jZ0 

EMT "0374 
.ENDM 

.MACRO .SDAT AREA > BUF , WCNT , CRTN=*1 » CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IIF IDN <CODE>»NOSETf ...CM4 <AREA> f . <BUF>t <UCNT>» r <CRTN>! 21 . t <CODE> 

.IIF DIF <CODE>>NOSETr ,..CM4 <AREA> f tO j <BUF> , <WCNT> r i ::CRTN> . 21 . » <C0DE:: 

.ENDM 

.MACRO .SDATC AREA j BUF , UCNT > CRTN > CODE 

.IF NDF . . .Ul 

.MCALL .MACS 

.MACS 

.ENDC 

.IIF IDN <CODE>fNOSETj ...CM4 <AREA> , , <BUF> , ■::UCNT> , r <CRTN> . 21 , , <CODE> 

,IIF DIF <CODE>fNOSET» ...CM4 <AREA:; - *0> <BUF> » <WCNT, r . <CRTN> . 21 . , <C0DE:: 

.ENDM 

.MACRO .SDATU AREA> BUF r WCNT , CRTN=*0 » CODE 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IIF IDN <CODE>»NOSET. . . . CM4 <AREA> > r <BUF:> t <WCNT:: f , <CRTN>r 21 . » <CODE> 

.IIF DIF <CODE>.NOSET, . . .CM4 <AREA>» *0 r <BUF> > <UCNT>.. , < CRTN> r 21 . . <C0PE:: 

.ENDM 

.MACRO .SDTTM AREA » ADDR » CODE 

.IF NDF . ..VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CMA <AREA>»32.»0»<C0DE> 

...CM2 <ADDR>»2.jX 

.ENDM 

•MACRO .SERR 

MOV *4.*''0400.X0 

EMT "0374 
.ENDM 

.MACRO .SETTO ADDR 

.IF NDF . ..VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CMS <ADDR> 

EMT "0354 



B-16 Appendix 



.ENDM 

.MACRO .SCCA AREA»ADDR>CODE 

.IF NDF ...yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>r29.»0><C0DE> 

...CM2 <ADDR>»2.»X 

.ENIiM 

.MACRO .SFPA AREAiADDRjCODE 

.IF NDF .. .yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>»24. »Of<C0DE> 

..,CM2 <ADDR>.2..X 

.ENDM 

.MACRO .SPCPS AREA.ADDRjCDDE 

.IF NDF ...yi 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>!33..O,<C0DE> 

...CM2 <ADDR>.2.fX 

.ENDM 

.MACRO .SPFUN AREA» CHAN t FUNC i BUF . UCNT.BLK »CRTN» CODE 

.IF NDF .. .yi 

.MCALL .MACS 

.MACS 

.ENDC 

. . . CMl <AREA> . 26 . . <CHAN> » <CODE> 

...CM2 <BLK>.2. 

...CM2 <BUF>.4. 

...CM2 <WCNT>f6. 

.IF NB FUNC 

.NTYPE ...y2»FUNC 

.IF NE ...y2-"027 

.IIF DIF <CDDE>rNOSET.. . .CM2 #"0377.8. ... B 

...CM2 <FUNC>.9....B 

.IFF 

...CM2 <FUNC 'S"0400+"0377> . 8 « 

.ENDC 

.ENDC 

...CM2 <CRTN>.10.»X.X 

.ENDM 

.MACRO .SRESE 

EMT "0352 
.ENDM 

.MACRO .SPND 

MOV ♦1«"0400>Z0 

EMT "0374 
.ENDM 

.MACRO .SYNCH AREA. PIC 

.IF B PIC 

,I1F NB <AREA> MOV AREA.%4 

.IFF 

.IF NB AREA 

MOM %7.%4 

ADD *AREA-..%4 

.ENDC 
.ENDC 

MOV e#-054.X5 
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JSR 



5..e"0324<5.> 



.ENOH 






.HACRO 


.TIHIO 


TBK»HI»LO 




JSR 


Z5,e«TIMIT 




.UORO 


TBK-. 




.WORD 







• WORD 


HI 




.WORD 


LO 


.ENDM 






.MACRO 


.TLOCK 






Moy 


*7.*''0400>%0 




EMT 


"0374 



AREA.AriDRfCODE 



,ENDM 

.MACRO .TRPSE 

.IF NDF .. .VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>,3. »Oi<CODE> 

...CM2 <ADDR>»2.>X 

.ENDM 



.MACRO 


.TTINR 






EMT 


"0340 


.ENDM 






.MACRO 


.TTYIN 


CHAR 




EMT 


"0340 




BCS 


.-2. 


.IF NB 


<CHAR> 




.IF niF 


<CHAR> 


>R0 




MOVE 


20 > CHAR 


.ENDC 






.ENDC 






.ENDM 






.MACRO 


.TTOUT 






EMT 


"0341 


.ENDM 






.MACRO 


.TTYOU 


CHAR 



.IF NB <CHAR> 
.IF DIF <CHAR>»RO 

MOVB CHARfZO 



.ENDC 






.ENDC 








EMT 


"0341 




BCS 


.-2. 



.ENDM 



AREAtTIME>CODE 



.MACRO .TUAIT 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 <AREA>f20.»0»<C0DE> 

...CM2 <TIME>f2.fX 

.ENDM 



.MACRO .UNLOC 

EMT 
.ENDM 

.MACRO .UNMAP 
.IF NDF ...VI 
.MCALL .MACS 



"0347 
AREA>ADDRfCODE 
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.MACS 
.EMBC 
«■ * i Cno 
, ..CM2 
>ENDH 



<AREft>.30.!5. 
<ADDR>»2.»X 



!<CODE> 



.MACRO .UNPRO 

.IF NDF ...VI 

.MCALL .MACS 

.MACS 

.ENDC 

...CM6 

...CM2 

.EWfiM 



AREA>ADDRrCODE 



<AREA>j25.»lr<CQIiE> 
<ADDR>»2,»X 



.MACRO .IWilT CHAN 

.IF NDF ...Ul 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EQ . . .Vl-1 

EMT 
.IFF 
.IF B <CHAN> 

CLR ZO 
.IFF 

.NTYPE ,.,y2fCHAN 
.IF EQ ...y2-"027 
.IF IDN <CHAN>r*0 



0<240+CHAN> 



.IFF 

.ENDC 
.IFF 



.ENDC 
.ENDC 

.ENDC 
.ENDM 



CLR 
MOV 



CLR 
BISB 



EMT 



ZO 
CHANfZO 



%0 
CHAN»ZO 



'0374 



.MACRO .HDBBK 

.MCALL .WDBDF 

.UDBDF 

.BYTE 
.BYTE 
.UORD 
.UORD 
.UORD 
.WORD 
.WORD 
.UORD 

.ENDM 



WNAPR.UNSIZ»WNRID.UNOFFjUNLEN»UNSTS 



WNAPR 

UNSIZ 
UNRID 
MNOFF 
UNLEN 
UNSTS 



.MACRO 

U.NID 

U.NAPR 

U.NBAS 

U.NSIZ 

U.NRID 

U.NOFF 

U.NLEN 

W.NSTS 

U.NLGH 

US.CRU 

US.UNM 

US.ELU 

WS.MAP 



.UDBDF 
=0 
= 1 
=2. 
= 4. 
= 6. 
= "010 
= "012 
= "014 
= "01* 
="0100000 
="040000 
="020000 
="0400 
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.ENDM 

.MACRO .URITC AREA » CHANtBUF.WCNT , CRTN» BLK , CODE 

.IF NDF . . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EO , . .Vl-1 

...CMS <CRTN> 

...CMO <WCNT> 

...CMO <BUF> 

...CMO <CHAN> 

EMT "0<220+AREA> 
.IFF 

...CM4 <AREA>.<CHAN>»<BUF>f<WCNT>f<BLK>.<CRTN>,9.,<C0DE> 
.ENDC 
.ENDM 

AREA. CHAN. EUF.WCNT»BLK»CRTN=*lf CODE 



.MACRO 


.WRITE 


.IF NDF 


. . .VI 


.MCALL 


.MACS 


.MACS 




.ENDC 




.IF EG 


...Vl-1 


. . .CM5 


<UCNT> 


. . .CMO 


*1 


...CMO 


<BUF> 


...CMO 


<CHAN> 




EMT 



■'0<220 + AREA> 
.IFF 

. . .CM4 <area:: .<chan:: . <buf>.<ucnt>.<:blk>.<crtn>.9. .<C0DE> 

.ENDC 
.ENDM 

.MACRO .WRITW AREA. CHAN. BUF .MCNT . BLK. CRTN=#0. CODE 

.IF NDF , . .VI 

.MCALL .MACS 

.MACS 

.ENDC 

.IF EGl . . .Vl-1 

...CMS <WCNT> 

,,.CMO 

...CMO <BUF> 

...CMO <CHAN> 

EMT "0<220+AREA> 
.IFF 

. . . CM4 <AREA> . <CHAN> . <EUF> , <UCNT> . <BLK> . <CRTN> . 9 . , <CODE> 
.ENDC 
.ENDM 
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INDEX 



Abort entry points, 2-30 
Addressing modes, 1-10 
AJFLT system subroutine, 3-1 
Argument block, 1-8 
Argument parameters, 

Droorammed requests; 2—1 
Arguments, 

blank, 1-9 
Assembly language, 

display support, A-1 
Asynchronous I/O, 1-19 
Attaching a terminal, 2-69 



.CRAW programmed request, 2-11 
.CRRG programmed request, 2-14 
CSI, 1-18 

special mode, 2-21 
CSI option information, 

passing, 2-18 
.CSIGEN programmed request, 2-15 

r*C T Cnr' y-sy^^/^v^Tnma/^ ir ami ad ^ O — "] 

.CSTAT programmed request, 2-23 

.CTIMIO macro, 2-24 

CTRL/C, 2-107 

CTRL/D, 2-89 

CVTTIM system subroutine, 3-5 



B 



Background job, 

directing control to, 2-3 
Blank arguments, 1-9 
.BLANKS graphics macro, A-3 



CALL statement, 1-44 
.CDFN programmed request, 2-2 
.CHAIN programmed request, 2-3 
CHAIN system subroutine, 3-1, 

See Also .CHAIN programmed 

request. 
Channel , 

freeing, 2-85 
Channel status information, 2-23 

1-37 
Character string functions, 1-55, 
1-56 
allocating character string 

variables, 1-57 
passing strings, 1-58 
using quoted-str ing literals, 
1-59 
.CHCOPY programmed request, 2-5 
•CLEAR graphics macro, A-4 
.CLOSE programmed request, 2-7 
CLOSEC system subroutine, 3-2 
•CMKT programmed request, 2-8 
.CNTXSW programmed request, 2-9 
Command interpretation, 1-18 
Completion routines, 1-20, 1-37 
CONCAT system subroutine, 3-4 
Console terminal character input, 

2-134 
Console terminal character 

output, 2-136 
Context switching, 2-9 



Date, 

setting, 2-112 
Date information, 2-25 
.DATE programmed request, 2-25 
.DELETE programmed request, 2-26 
Detaching a terminal, 2-71 
Device, 1-16 

status information, 2-36 
Device blocks, 1-11, 1-39 
Device handler macro, 

.CTIMIO, 2-24 

.DRAST, 2-30 

.DRBEG, 2-31 

•DRBOT, 2-31 

.DRDEF, 2-32 

.DREND, 2-33 

.DRFIN, 2-34 

.DRSET, 2-34 

.DRVTB, 2-35 

.QELDF, 2-86 

.TIMIO, 2-129 
Device handlers, 1-26 

releasing, 2-45 

special functions, 2-121 

termination table, 2-33 

time-out calls, 2-129 
.DEVICE programmed request, 2-28 
DEVICE system subroutine, 3-5, 
See Also .DEVICE programmed 
request. 
DEALT display halt instruction, 

A-14 
Display file handler, 

description, A-1 

using, A-15 
Display file structure, 

BASIC-11 graphics software, 
A- 20 

main file/subroutine, A-19 

subroutine calls, A-18 



Index-1 



INDEX 



Display processor mnemonics, A-23 
DJFLT system subroutine, 3-6 
DJSR subroutine call instruction, 

A-13 
DNAME load name register 

instruction, A-14 
.DRAST device handler macro, 

2-30 
.DRBEG device handler macro, 2-31 
.DRBOT device handler macro, 2-31 
•DRDEF device handler macro, 2-32 
.DREND device handler macro, 2-33 
DRET subroutine return 

instruction, A-13 
•DRFIN device handler macro, 2-34 
•DRSET device handler macro, 2-34 
•DRVTB device handler macro, 2-35 
DSTAT display status instruction, 

A-14 
.DSTATUS programmed request, 2-36 
Dynamic region, 
creating, 2-14 



.ELAW programmed request, 2-38 

•ELRG programmed request, 2-39 

EMT codes, 1-3 

EMT instructions, 1-3 

.ENTER programmed request, 2-39 

Entry point. 



Entry point, 
abort, 2-30 
interrupt, 2-30 




A-13 
Extended memory, 

programmed requests, 1-24 
Extended memory monitor. 

See XM monitor. 



FB monitor, 1-2 

FORTRAN IV programs, 1-50 
.FETCH programmed request, 2-44 
Files, 

deleting, 2-26 
Foreground/background 

communications, 1-22 
Foreground/background 
environment, 
running a FORTRAN IV program, 
1-59 
-FORK macro, 2-46 
Format, 

programmed requests, 1-6 



FORTRAN IV, 

PSECT ordering, 1-41 
running a program, 1-59 

FORTRAN IV programs, 
foreground/background 
environment, 1-50 

FORTRAN programs, 

calculating workspace, 1-51 

FORTRAN/MACRO interface, 1-45 
calling FORTRAN programs, 1-48 
calling MACRO subroutines, 1-46 
subroutine register usage, 1-46 

Function reference, 1-44 



GETSTR system subroutine, 3-7 
•GMCX programmed request, 2-48 
Graphics macro calls, 

summary, A-21 
Graphics macros, A-3 
.GTIM programmed request, 2-49 
GTIM system subroutine, 3-8 
.GTJB programmed request, 2-50 
GTJB system subroutine, 3-8 
•GTLIN programmed request, 2-52 
GTLIN system subroutine, 3-10, 

See Also .GTLIN programmed 

request. 
,GVAL programmed request, 2-53 



H 



.HERR programmed request, 2-54 
High limit, 

setting program, 2-114 
.HRSET programmed request, 2-56 



I 

I/O, 

event driven, 1-19 
I/O channels, 

defining additional, 2-2 
lADDR system subroutine, 3-11 
lAJFLT system subroutine, 3-11 
lASIGN system subroutine, 3-12 
ICDFN system subroutine, 3-13 
ICHCPY system subroutine, 3-14 
ICLOSE system subroutine, 3-2 
ICMKT system subroutine, 3-15, 

See Also .CMKT programmed 

request. 
ICSI system subroutine, 3-16, 

See Also .CSISPC programmed 

request. 
ICSTAT system subroutine, 3-18 
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IDELET system subroutine, 3-19, 
See Also .DELETE programmed 
request. 
IDJFLT system subroutine, 3-20 
IDSTAT system subroutine, 3-21 
lENTER system subroutine, 3-21, 
See Also .ENTER programmed 
request. 
IFETCH system subroutine, 3-23, 
See Also .FETCH programmed 
request. 
IFREEC system subroutine, 3-24 
IGETC system subroutine, 3-24 
IGETSP system subroutine, 3-25 
IGTJB system subroutine, 3-8 
IJCVT system subroutine, 3-26 
ILUN system subroutine, 3-27 
INDEX system subroutine, 3-27 
Initialization and control, 1-15 

devices, 1-16 

error processing, 1-17 

input/output access, 1-16 

memory allocation, 1-15 
Input/output access, 1-16 
Input/output operations, 

completion routines, 1-20 

multi-terminal programmed 
requests, 1-22 

terminal input/output, 1-21 
INSERT system subroutine, 3-28 
.INSRT graphics macro, A-5 
INTEGER*4 support functions, 1-39 
.INTEN macro, 2-57 
Interrupt entry points, 2-30 
Interrupt service routine macro, 

.FORK, 2-46 

.INTEN, 2-57 

.SYNCH, 2-127 
Interrupt service routines, 1-25 
INTSET system subroutine, 3-28 
IPEEK system subroutines, 3-30 
IPEEKB system subroutines, 3-30 
IPOKE system subroutine, 3-31 
IPOKEB system subroutine, 3-31 
IQSET system subroutine, 3-32, 
See Also .QSET programmed 
request. 
IRAD50 system subroutine, 3-33 
IRCVD system subroutine, 3-34 
IRCVDC system subroutine, 3-34 
IRCVDF system subroutine, 3-35 
IRCVDW system subroutine, 3-36 
IREAD system subroutine, 3-36 
IREADC system subroutine, 3-38 
IREADF system subroutine, 3-39 
IREADW system subroutine, 3-40 
IRENAM system subroutine, 3-41, 
See Also .RENAME programmed 
request. 
IREOPN system subroutine, 3-42 



ISAVES sys 
ISCHED sys 
ISCOMP sys 
ISDAT syst 
ISDATC sys 
ISDATF sys 
ISDATW sys 
ISLEEP sys 
ISPFN syst 
ISPFNC sys 
ISPFNF sys 
ISPFNW sys 
ISPY syste 
ITIMER sys 
ITLOCK sys 
See Al 
reques 
ITTINR sys 
ITTOUR sys 
ITWAIT sys 
lUNTIL sys 
IWAIT syst 
IWRITC sys 
IWRITE sys 
IWRITF sys 
IWRITW sys 



tern subrou 
tern subrou 
tem subrou 
em subrout 
tem subrou 
tem subrou 
tem subrou 
tem subrou 
em subrout 
tem subrou 
uem subrou 
tem subrou 
m subrouti 
tem subrou 
tem subrou 
so .TLOCK 
t. 

tem subrou 
tem subrou 
tem subrou 
tem subrou 
em subrout 
tem subrou 
tem subrou 
tem subrou 
tem subrou 



tine 
tine 
tine 
ine, 
tine 
tine 
tine 
tine 
ine, 
tine 
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tine 

ne, 

tine 

tine 

prog 

tine 
tine 
tine 
tine 
ine , 
tine 
tine 
tine 
tine 



, 3-43 
, 3-44 
, 3-90 

3-45 
, 3-46 
, 3-47 
, 3-47 
, 3-48 

3-48 
, 3-50 
, 3-51 
, 3-53 
3-54 
, 3-55 
, 3-56, 
rammed 

, 3-57 
s, 3-57 
, 3-59 
, 3-60 

3-61 
, 3-62 
, 3-61 
, 3-63 
, 3-64 



JADD system subrou 

JAFIX system subro 

JCMP system subrou 

JDFIX system subro 

JDIV system subrou 

JICVT system subro 

JJCVT system subro 

JMOV system subrou 

JMUL system subrou 

Job communication, 

message transfer 

reading data, 2- 

Job status informa 

Job suspension, 

I/O completion, 

period of time, 

JSUB system subrou 

JTIME system subro 



Keyword macro arguments, 1-11 



LEN system subroutine, 3-71 
Linking, 

graphics programs, A-16 
Linking with FORLIB, 1-54 
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utine, 


, 3-65 


tine. 


3-65 


utine, 


, 3-66 


tine. 
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utine, 


, 3-67 


utine; 


, 3-68 


tine. 
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tine, 
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tion. 


2-50 


2-140 




2-138 




tine. 


3-70 


utine, 


, 3-70 
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Listing, 
System 
.LNKRT g 
Loading 
Loading 

regi 
.LOCK pr 
LOCK sys 
•LOOKUP 
standa 
system 
LOOKUP s 
,LPEN gr 



Macro Library, B-1 
raphics macro, A-5 
device handlers, 2-44 
values into device 
sters, 2-28 

ogramraed request, 2-58 
tem subroutine, 3-72 
programmed request, 
rd lookup, 2-61 

job lookup, 2-63 
ystem subroutine, 3-73 
aphics macro, A-7 



M 



Main-line code, 

change flow of control, 2-119 

resume flow, 2-124 

suspend flow, 2-124 
•MAP programmed request, 2-64 
Mapping a window to a region, 

2-64 
Memory, 

allocation, 1-15 
.MFPS programmed request, 2-65 
Monitor display support, A-2 
Monitor fixed-offset area, 1-3 
Monitor offset values, 

obtaining, 2-53 
.MRKT programmed request, 2-67 
MRKT system subroutine, 3-76 
.MTATCH programmed request, 2-69 
MTATCH system subroutine, 3-76 
.MTDTCH programmed request, 2-71 
MTDTCH system subroutine, 3-79 
.MTGET programmed request, 2-72 
MTGET system subroutine, 3-79, 
See Also .MTSET programmed 
request. 
.MTIN programmed request, 2-75 
MTIN system subroutine, 3-80 
.MTOUT programmed request, 2-76 
MTOUT system subroutine, 3-81 
•MTPRNT programmed request, 2-77 
MTPRNT system subroutine, 3-81 
•MTPS programmed request, 2-65 
.MTRCTO programmed request, 2-78 
MTRCTO system subroutine, 3-82, 
See Also .RCTRLO programmed 
request. 
.MTSET programmed request, 2-79 
MTSET system subroutine, 3-82, 
See Also .MTSET programmed 
request. 
.MTSTAT programmed request, 2-80 
MTSTAT system subroutine, 3-83 
Multi-terminal , 

feature, 1-2 



programmed requests, 1-22 
Multi-terminal programmed 
request, 

.MTATCH, 2-69 

•MTDTCH, 2-71 

.MTGET, 2-72 

.MTIN, 2-75 

.MTOUT, 2-76 

.MTPRNT, 2-77 

.MTRCTO, 2-78 

.MTSET, 2-79 

.MTSTAT, 2-80 
•MWAIT programmed request, 
MWAIT -system subroutine, 3- 



2-81 
3-84 



N 

.NAME graphics macro, A-8 
.NOSYN graphics macro, A-11 



2-82 
■84 



Primary driver macro, 2-31 
•PRINT programmed request, 2 
PRINT system subroutine, 3-8 
Program, 

suspension, 1-54 

termination or suspension, 1-23 
Programmed request, 

.CDFN, 2-2 

.CHAIN, 2-3 

.CHCOPY, 2-5 

•CLOSE, 2-7 

•CMKT, 2-8 

•CNTXSW, 2-9 

.CRAW, 2-11 

•CRRG, 2-14 

•CSIGEN. 2-15 

•CSISPC, 2-21 

•CSTAT, 2-23 

•DATE, 2-25 

•DELETE, 2-26 

.DEVICE, 2-28 

•DSTATUS, 2-36 

•ELAW, 2-38 

•ELRG, 2-39 

•ENTER, 2-39 

.EXIT, 2-42 

.FETCH, 2-44 

.GMCX, 2-48 

.GTIM, 2-49 

.GTJB, 2-50 

.GTLIN, 2-52 

•GVAL, 2-53 

•HERR, 2-54 
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.HRESET, 


2-56 


.LOCK, 2- 


-58 


.LOOKUP, 


2-60 


.MAP, 2-64 


.MFPS, 2- 


-65 


.MRKT, 2- 


-67 


.MTATCH, 


2-69 


.MTDTCH, 


2-71 
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.MTIN, 2-75 
.MTOUT, 2-76 
.MTPRNT, 2-77 
.MTPS, 2-65 
.MTRCTO, 2-78 
.MTSET, 2-79 
.MTSTAT, 2-80 
.MWAIT, 2-81 
PRINT, 2-82 
PROTECT, 2-83 
PURGR. 2-8 5 



.PURGE, 
.QSET, l-v, I 
.RCTRLO, 2-89 



j.xv-i^, 2-85 
SET, 2-87 



. Kk,iKL,U, Z- 

.RCVD, 2-90 
.RCVDC, 2-92 
.RCVDW, 2-93 
.RDBBK, 2-94 
.RDBDF, 2-94 
.READ, 2-94 
.READC, 2-98 
.READW, 2-101 
.RELEASE, 2-44 
.RENAME, 2-103 
REOPEN, 2-104 
RKIIM. p-i^a 



.RSUM, 2-124 
.SAVESTATUS, 2-105 
.SCCA, 2-107 



.RSUM, 2-124 
.SAVES' 
. SCCA , i — J. u / 
SDAT, 2-109 
SDATC, 2-111 
.SDATW, 2-111 
.SDTTM, 2-112 
.SERR, 2-54 
.SETTOP, 2-114 
.SFPA, 2-117 
.SPCPS, 2-119 
.SPFUN, 2-121 
.SPND, 2-124 
.SRESET, 2-126 
•TLOCK, 2-131 
.TRPSET, 2-132 
•TTINR, 2-134 
.TTOUTR, 2-136 
.TTYIN, 2-134 
.TTYOUT, 2-136 
.TWAIT, 2-138 

iTXTT r\n^ -5_ c Q 

.UNMAP, 2-139 
.UNPROTECT, 2-83 
.WAIT, 2-140 
.WDBBK, 2-141 



Programmed request, (Cont.) 
.WDBDF, 2-142 
.WRITC, 2-144 
.WRITE, 2-143 
.WRITW, 2-145 
Programmed requests, 

allocating system resources, 

1-17 
argument block, 1-8 
argument t^arameters, 2—1 
command interpretation, 1-18 
conversion, 1-28 
EMT codes, 1-3 
errors, 1-12 
extended memory function, 

1-24 
extended memory monitor, 1-2 
file operations, 1-18 
foreground/background 

communications, 1-22 
foreground/background mionitor , 

1-2 
format, 1-6 
implementation, 1-3 
initialization and control, 

1-15 
input/output operations, 1-19 
multi — terminal - 1 — 2, 1 — 22 
program termination or 

suspension, 1-23 
queue elements, 2-87 
reporting status, 1-17 
services, 1-1 
single-job monitor, 1-2 
summary, 1-30 

system control path flow, 1-4 
system job communications, 

system job support, 1-2 

timer support, 1-23 

use of .MCALL directive, 1-6 

user stack, 1-7 

using, 1-14 
.PROTECT programmed request, 

2-83 
PS, 

accessing, 2-65 
.PURGE programmed request, 2-85 
PURGE system subroutine, 3-85 
PUTSTR system subroutine, 3-85 



.QELDF macro, 2-86 

-QSET programmed request. 

Queue element, 

requirement, 1-43 
Queue element offsets, 

defining, 2-87 



2-87 
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R50ASC system subroutine, 3-86 
RAD50 system subroutine, 3-86 
Radix-50, 

conversion, 1-55 
RCHAIN system subroutine, 3-87 
.RCTRLO programmed request, 2-89 
RCTRLO system subroutine, 3-87 
•RCVD programmed request, 2-90 
•RCVDC programmed request, 2-92 
.RCVDW programmed request, 2-93 
•RDBBK programmed request, 2-94 
.RDBDF programmed request, 2-94 
.READ programmed request, 2-94 
•READC programmed request, 2-98 
Reading into memory, 2-94 
•READW programmed request, 

2-101 
Region, 

eliminating, 2-39 
Region definition block, 
defining symbols, 2-94 
symbolic offset names, 2-94 
•RELEASE programmed request, 2-44 
.REMOV graphics macro, A-9 
•RENAME programmed request, 2-103 
Renaming files, 2-103 
•REOPEN programmed request, 2-104 
REPEAT system subroutine, 3-88 
Reporting status, 1-17 
•RESTR graphics macro, A-9 
Restrictions, 

completion routines, 1-21, 1-38 
extended memory programmed 

requests, 1-25 
FORTRAN IV programs, 1-43 
RESUME system subroutine, 3-89 
Routines, 

completion, 1-22 
•RSUM programmed request, 2-124 



•SAVESTATUS programmed request, 

2-105 
•SCCA programmed request, 2-107 
SCCA system subroutine, 3-89 
SCOMP system subroutine, 3-90 
SCOPY system subroutine, 3-91 
-SCROL graphics macro, A-9 
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•SDTTM programmed request, 2-112 
SECNDS system subroutine, 3-91 
•SERR programmed request, 2-54 
SET command option table, 2-34 
SETCMD system subroutine, 3-92 



•SETTOP programmed request, 
extended memory environment, 
2-116, 2-114 
•SFPA programmed request, 2-117 
SJ monitor, 1-2 
Soft error codes, 2-55 
Software reset, 2-126 
•SPCPS programmed request, 2-119 
•SPFUN programmed request, 2-121 
•SPND programmed request, 2-124 
•SRESET programmed request, 2-126 
•START graphics macro, A-10 
•STAT graphics macro, A-10 
Status information, 

channels, 2-23 

devices, 2-36 

multi-terminal system, 2-80 

system jobs, 2-50, 3-8 

terminal unit, 2-72 

window mapping, 2-48 
•STOP graphics macro, A-11 
Stopping in-progress I/O 

transfers, 2-56 
STRPAD system subroutine, 3-93 
Subroutine, 

register usage, 1-46 
SUBSTR system subroutine, 3-94 
Suspending execution of a job, 

2-81, 2-138, 2-140 
SUSPND system subroutine, 3-94 
Swapping the USR, 1-14, 1-40 
•SYNC graphics macro, A-11 
•SYNCH macro, 2-127 
Synchronous I/O, 1-19 
SYSLIB, 

conversion calls, 1-55 
System communication area, 1-3 
System conventions, 

addressing modes, 1-10 

blank arguments, 1-9 

channels and channel numbers, 
1-11 

device blocks, 1-11 

keyword macro arguments, 1-11 

programmed request errors, 1-12 

programmed request format, 1-6 

USR requirement, 1-12 
System jobs, 

communications, 1-24 

inter-job communications, 2-90, 
2-109, 3-34, 3-45 

status information, 2-50, 3-8 

support, 1-2 
System macro library, 1-1 
System Macro Library listing, B-1 
System subroutine, 

AJFLT, 3-1 

CHAIN, 3-1 

CLOSEC, 3-2 

CONCAT, 3-4 
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System subroutine, (Cont.) 
CVTTIM, 3-5 
DEVICE, 3-5 
DJFLT, 3-6 
GETSTR, 3-7 
GTIM, 3-8 
GTJB, 3-8 
GTLIN, 3-10 
lADDR, 3-11 
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lASIGN, 3-12 
ICDFN, 3-13 
ICHCPY, 3-14 
ICLOSE, 3-2 
ICMKT, 3-15 
ICSI, 3-16 
ICSTAT, 3-18 
IDELET, 3-19 
IDJFLT, 3-20 
IDSTAT, 3-21 
lENTER, 3-21 
IFETCH, 3-23 
IFREEC, 3-24 
IGETC, 3-24 
IGETSP, 3-25 
IGTJB, 3-8 
IJCVT, 3-26 

INDEX, 3-27 
INSERT, 3-28 
INTSET, 3-28 
IPEEK, 3-30 
IPEEKB, 3-30 
IPOKE, 3-31 
IPOKEB, 3-31 
IQSET, 3-32 
IRAD50, 3-33 
IRCVD, 3-34 
IRCVDC, 3-34 
IRCVDF, 3-35 
IRCVDW, 3-36 
IREAD, 3-36 
IRBADC, 3-38 
IREADF, 3-39 
IREADW, 3-40 
IRENAM, 3-41 
IREOPN, 3-42 
ISAVES, 3-43 
ISCHED, 3-44 
ISCOMP, 3-90 
ISDAT, 3-45 
ISDATC, 3-46 
ISDATF, 3-47 
ISDATW, 3-47 
ISLEEP, 3-48 

TCP CM "J—zlQ 

ISPFNC, 3-50 
ISPFNF, 3-51 
ISPFNW, 3-53 
ISPY, 3-54 



System subroutine, (Cont. 
ITIMER, 3-55 
ITLOCK, 3-56 
ITTINR, 3-57 
ITTOUR, 3-57 
ITWAIT, 3-59 
lUNTIL, 3-60 
IWAIT, 3-61 
IWRITC, 3-62 

TMDTTP 1—(^1 
■^'"■■^ '■ " r " " -^ 

IWRITF, 3-63 
IWRITW, 3-54 
JADD, 3-64 
JAFIX, 3-65 
JCMP, 3-6 5 
JDFIX, 3-66 
JDIV, 3-67 
JICVT, 3-67 
JJCVT, 3-68 
JMOV, 3-68 
JMUL, 3-69 
JSUB, 3-70 
JTIME, 3-70 
LEN, 3-71 
LOCK, 3-72 
LOOKUP, 3-73 
MRKT, 3-76 
MTATCH, 3-76 
MTDTCH, 3-79 
MTGET, 3-79 
MTIN, 3-80 
MTOUT, 3-81 
MTPRNT, 3-81 
MTRCTO, 3-82 
MTSET, 3-82 
MTSTAT, 3-83 
MWAIT, 3-84 
PRINT, 3-84 
PURGE, 3-85 
PUTSTR, 3-85 
R50ASC, 3-86 
RAD50, 3-86 
RCHAIN, 3-87 
RCTRLO, 3-87 
REPEAT, 3-88 
RESUME, 3-89 
SCCA, 3-89 
SCOMP, 3-90 
SCOPY, 3-91 
SECNDS, 3-91 
SETCMD, 3-92 
STRPAD, 3-93 
SUBSTR, 3-94 
SUSPND, 3-94 
TIMASC, 3-95 
TIME 3—96 
TRANSL, 3-97 
TRIM, 3-98 
UNLOCK, 3-99 
VERIFY, 3-99 
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System subroutine library, 1-1 
capabilities, 1-36 
channel numbers, 1-37 
completion routines, 1-37 
device blocks, 1-39 
FORTRAN IV restrictions, 1-43 
INTEGER*4 support, 1-39, 1-55 
queue element requirement, 1-43 
system conventions, 1-37 
using, 1-35 
USR requirements, 1-40 

System subroutine summary, 1-59 

System subroutines, 3-1 



•UNMAP programmed request, 2-139 
Unmapping a window, 2-139 
•UNPROTECT programmed request, 

2-83 
USR, 

locking in memory, 2-58 

releasing from memory, 2-59 
USR requirements, 1-12, 1-40 

strategies in USR swapping, 
1-41 

USR lockout and timing, 1-42 



Terminal input/output, 1-21 
Terminating a program, 2-42 
TIMASC system subroutine, 3-95 
Time, 

obtaining, 2-49 

setting, 2-112 
Time conversion and date access, 

1-54 
TIME system subroutine, 3-96 
Timer support, 1-23 
.TIMIO macro, 2-129 
•TLOCK programmed request, 2-131 
•TRACK graphics macro, A-11 
TRANSL system subroutine, 3-97 
Trap, 

interception, 2-132 
Trap addresses, 

setting, 2-117 
TRIM system subroutine, 3-93 
.TRPSET programmed request, 2-132 
•TTINR programmed request, 2-134 
.TTOUTR programmed request, 2-136 
.TTYIN programmed request, 2-134 
.TTYOUT programmed request, 2-136 
.TWAIT programmed request, 2-138 
Two-word integer support 
(INTEGER*4) , 1-55 



u 

.UNLNK graphics macro, A-12 
.UNLOCK programmed request, 2-58 
UNLOCK system subroutine, 3-99 



Vector control protection, 2-83 
Vector tables for multi-vector 

device, 2-35 
VERIFY system subroutine, 3-99 
Version 1, 

programmed requests, 1-26 
Version 2, 

programmed requests, 1-26 
Version 3, 

programmed requests, 1-27 
Version 4, 

programmed requests, 1-27 



.WAIT programme 
.WDBBK programm 
.WDBDF programm 
Window, 2-11 

eliminating. 
Window definiti 

symbol defini 

symbolic offs 
Workspace, 

FORTRAN progr 
.WRITC programm 
•WRITE programm 
Writing from me 
.WRITW programm 



w 

d request, 2-140 
ed request, 2-141 
ed request, 2-142 

2-38 

on block, 

tion, 2-141 

et names, 2-142 

ams, 1-51 

ed request, 2-144 

ed request, 2-143 

mory, 2-143 

ed request, 2-145 



XM monitor, 1-2 

extended memory functions, 1-24 
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